The Beneficiaries webhook notifies subscribed API clients when a beneficiary review is approved or rejected. It sends an HTTP POST with the beneficiary’s current details to the client’s registered endpoint.

Object Structure Samples

{
  "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "Name": "beneficiary.review.approved",
  "AccountId": "8c9c4a1e-3b2a-4a3d-9c2b-6f6b1a2e9d10",
  "Data": {
    "Beneficiary": {
      "Id": "6c6a9c1a-2e4f-4a3d-9c2b-6f6b1a2e9d10",
      "Type": "Individual",
      "Status": "Approved",
      "FirstName": "John",
      "LastName": "Doe",
      "BirthDate": "1990-05-14",
      "CompanyName": null,
      "PaymentMethod": "Swift",
      "Currency": "USD",
      "BankDetails": {
        "BankCountry": "US",
        "BankBranch": null,
        "BankCode": null,
        "SwiftCode": "BOFAUS3N",
        "Iban": null,
        "AccountNumber": "0001112223",
        "RoutingType": "ABA",
        "RoutingCode": "026009593",
        "AdditionalRoutingType": null,
        "AdditionalRoutingCode": null
      },
      "PaymentReason": {
        "Id": "9",
        "Description": "Transfer For Services Up To 250K"
      },
      "Identity": {
        "IdNumber": "123456789"
      },
      "Contact": {
        "Email": "[email protected]"
      },
      "Address": {
        "Country": "US",
        "State": "NY",
        "City": "New York",
        "Address": "123 Main St",
        "ZipCode": "10001"
      },
      "CreatedAt": "2026-07-01T10:00:00+00:00",
      "UpdatedAt": "2026-07-20T09:15:00+00:00"
    }
  },
  "CreateAtUtc": "2026-07-20T09:15:00Z"
}

{
  "Id": "f1e2d3c4-b5a6-4978-8899-aabbccddeeff",
  "Name": "beneficiary.review.rejected",
  "AccountId": "8c9c4a1e-3b2a-4a3d-9c2b-6f6b1a2e9d10",
  "Data": {
    "Beneficiary": {
      "Id": "7d7b0d2b-3f5a-4b4e-ad3c-7a7c2b3f0e21",
      "Type": "Company",
      "Status": "Rejected",
      "FirstName": null,
      "LastName": null,
      "BirthDate": null,
      "CompanyName": "Acme Trading Ltd",
      "PaymentMethod": "Local",
      "Currency": "EUR",
      "BankDetails": {
        "BankCountry": "DE",
        "BankBranch": null,
        "BankCode": null,
        "SwiftCode": null,
        "Iban": "DE89370400440532013000",
        "AccountNumber": null,
        "RoutingType": null,
        "RoutingCode": null,
        "AdditionalRoutingType": null,
        "AdditionalRoutingCode": null
      },
      "PaymentReason": {
        "Id": "3",
        "Description": "Invest In Other Assets Abroad"
      },
      "Identity": {
        "IdNumber": "HRB123456"
      },
      "Contact": {
        "Email": "[email protected]"
      },
      "Address": {
        "Country": "DE",
        "State": null,
        "City": "Berlin",
        "Address": "Unter den Linden 1",
        "ZipCode": "10117"
      },
      "CreatedAt": "2026-07-10T08:30:00+00:00",
      "UpdatedAt": "2026-07-20T11:42:00+00:00"
    }
  },
  "CreateAtUtc": "2026-07-20T11:42:00Z"
}

Overview

Event Name	Description
`beneficiary.review.approved`	Sent when Okoora's back office approves a beneficiary that was pending review.
`beneficiary.review.rejected`	Sent when Okoora's back office rejects a beneficiary that was pending review.

Object Structure Samples

Data Object For Beneficiaries

Top-level object delivered as the HTTP request body.

Property	Type	Description
`Id`	string (GUID)	Unique identifier generated for this webhook delivery attempt.
`Name`	string	Event type identifier. One of the values listed in Overview: `beneficiary.review.approved`, `beneficiary.review.rejected`.
`AccountId`	string (GUID)	Identifier of the API client account the beneficiary belongs to.
`Data`	object	Container for the beneficiary payload. See Data.
`CreateAtUtc`	string (date-time)	UTC timestamp at which the webhook request object was created.

Data

Nested inside Data Object.Data.

Property	Type	Description
`Beneficiary`	object	The beneficiary's full details at the time of the review decision. See Beneficiary.

Beneficiary

Nested inside Data.Beneficiary.

Property	Type	Description
`Id`	string (GUID)	Unique identifier of the beneficiary.
`Type`	string	Beneficiary type enum, serialized as its member name. Possible values: `Company`, `Individual`.
`Status`	string	Beneficiary status enum, serialized as its member name. Possible values: `New`, `Pending`, `Approved`, `Deleted`, `Rejected`. In practice this webhook only fires with `Approved` or `Rejected`.
`FirstName`	string or null	First name of the beneficiary. Populated for individual beneficiaries.
`LastName`	string or null	Last name of the beneficiary. Populated for individual beneficiaries.
`BirthDate`	string (date, `yyyy-MM-dd`) or null	Date of birth. `null` if the underlying date was never set (default/unset value).
`CompanyName`	string or null	Legal name of the beneficiary. Populated for company beneficiaries.
`PaymentMethod`	string	Transfer method enum, serialized as its member name. Possible values: `Local`, `Swift`.
`Currency`	string	Currency code of the beneficiary's bank account.
`BankDetails`	object	Bank account details. See BankDetails.
`PaymentReason`	object	Reason for payments to this beneficiary. See PaymentReason.
`Identity`	object	Identity document details. See Identity.
`Contact`	object	Contact details. See Contact.
`Address`	object	Address details. See Address.
`CreatedAt`	string (date-time with offset)	When the beneficiary was created.
`UpdatedAt`	string (date-time with offset)	When the beneficiary was last updated (reflects the approval/rejection that triggered this webhook).

BankDetails

Nested inside Data.Beneficiary.BankDetails.

Property	Type	Description
`BankCountry`	string	ISO country code of the beneficiary's bank.
`BankBranch`	string or null	Bank branch identifier.
`BankCode`	string or null	Bank code.
`SwiftCode`	string or null	SWIFT/BIC code of the bank.
`Iban`	string or null	IBAN of the beneficiary's account.
`AccountNumber`	string or null	Local account number (used when no IBAN applies).
`RoutingType`	string or null	Routing code type enum, serialized as its member name. Possible values: `BSB`, `CNAPS`, `IFSC`, `CLABE`, `SORT_CODE`, `ABA`, `BANK_CODE`, `INSTITUTION_NUMBER`, `BRANCH_CODE`, `BANK_BRANCH`, `TRANSIT_NUMBER`, `ROUTING_NUMBER`. `null` if no routing type is set.
`RoutingCode`	string or null	The routing code value corresponding to `RoutingType`.
`AdditionalRoutingType`	string or null	Secondary routing code type enum, serialized as its member name. Same possible values as `RoutingType`. `null` if not applicable.
`AdditionalRoutingCode`	string or null	The routing code value corresponding to `AdditionalRoutingType`.

PaymentReason

Nested inside Data.Beneficiary.PaymentReason.

Property	Type	Description
`Id`	string	Numeric payment-reason code, serialized as a string. Corresponds to the underlying payment reason enum value: `0`=Other, `1`=Invest In Company Stocks, `2`=Invest In Real Estate Abroad, `3`=Invest In Other Assets Abroad, `4`=Foreign Resident Loan, `5`=Company Owner Loan, `6`=Return Of Investment Fund (With Accountant Approval), `7`=Partnership Invest, `9`=Transfer For Services Up To 250K, `10`=Transfer For Services Over 250K, `11`=Import Of Goods Not Including Books, `14`=Education Abroad, `17`=Relative Residing Overseas, `18`=Transfer To An Israeli Resident, To An Israeli Bank Only, `19`=Transfer To My Account Abroad, `20`=Tourism Services, `21`=Third Party Transfer, `22`=Transportation Services Overseas, `24`=Software Development Or Online Services, `25`=Salaries ILS Only, `26`=Invest In Options, `27`=Advertising Abroad.
`Description`	string	Free-text description of the payment reason if one was supplied; otherwise falls back to the payment-reason enum member name (e.g. `ServicesUpTo250k`) corresponding to `Id`.

Identity

Nested inside Data.Beneficiary.Identity.

Property	Type	Description
`IdNumber`	string	Identity/registration number of the beneficiary (national ID for individuals, company registration number for companies).

Contact

Nested inside Data.Beneficiary.Contact.

Property	Type	Description
`Email`	string or null	Contact email address of the beneficiary.

Address

Nested inside Data.Beneficiary.Address.

Property	Type	Description
`Country`	string	ISO country code of the beneficiary's address.
`State`	string or null	State or province.
`City`	string or null	City.
`Address`	string or null	Street address.
`ZipCode`	string or null	Postal/ZIP code.