Skip to Content
Apex Settlement
Webhooks

beneficiary.updated

Sent when a Beneficiary is registered, verified or blocked. data is the Beneficiary as GET /v1/beneficiaries/{id} answers it.

Each delivery is a POST of the event as JSON to every active endpoint subscribed to its type, signed in Apex-Signature. Answer any 2xx within ten seconds to acknowledge it; anything else, a redirect included, is a failure, retried after 30 seconds and then twice as long each time (at most four hours apart) for fifteen attempts, about a day in all. An endpoint that has failed for 24 hours is disabled. The same event may arrive more than once: deduplicate on its id (also in Apex-Event-Id). Events about a Platform's End Customer go to the Platform's endpoints and carry end_customer_id.

Header Parameters

Apex-Signature*string

t=<unix seconds>,v1=<hex HMAC-SHA256>: the HMAC, keyed with the endpoint's whole whsec_… signing secret, of the timestamp, a full stop and the raw request body (<t>.<body>). Recompute it over the exact bytes received, compare in constant time, and refuse a timestamp far from your clock to stop replays. It is minted afresh on every attempt.

Apex-Event-Id*string

The event's id; the same on every attempt and every redelivery.

Formatuuid
Apex-Event-Type*string

The event's type.

Apex-Delivery-Attempt*string

Which attempt this is, from 1.

Request Body

application/json
  1. body

The beneficiary.updated event as it is delivered.

created_at*string

created_at is when the change happened, in UTC.

Formatdate-time
data*

The resource as it stands after the change.

end_customer_id?string

end_customer_id says which of a Platform's End Customers the event is about.

id*string

id is the event's id, the same on every attempt and redelivery: a receiver deduplicates on it.

type*string

The event type.

Response Body

Acknowledged. Any 2xx counts; the body is kept, up to 2 KB, for the delivery log and otherwise ignored.

Example Requests
POST/beneficiary.updated

The beneficiary.updated event as it is delivered.

Request Body
application/json
{  "created_at": "2026-11-12T09:31:05Z",  "data": {    "asset": "EUR",    "available": true,    "country": "DE",    "created_at": "2026-11-12T08:02:11Z",    "details": {      "iban": "DE89370400440532013000",      "name": "Berlin Supplies GmbH"    },    "id": "7a1e4c2b-9d3f-4e8a-b6c5-1f2e3d4c5b6a",    "kind": "external",    "name": "Berlin Supplies GmbH",    "party_type": "business",    "state": "verified",    "updated_at": "2026-11-12T08:15:00Z"  },  "id": "9b2f7c1e-5d4a-5e8b-a3c6-0f1d2e3a4b5c",  "type": "beneficiary.updated"}
Header Parameters
{  "Apex-Signature": "string",  "Apex-Event-Id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "Apex-Event-Type": "string",  "Apex-Delivery-Attempt": "string"}