Skip to main content
WEBHOOK

Authorizations

Authorization
string
header
required

JWT bearer token. Include as Authorization: Bearer <token>. See the Authentication guide for how to obtain one.

Body

application/json

Body of every webhook delivery. The event metadata sits at the top level and the event object in data. The body is identical on every retry and replay of the same event, and it is the exact content covered by the Webhook-Signature header.

type
enum<string>
required

The specific event type within a resource, sent as the type field of each delivery body.

Available options:
BENEFICIARY_INSTRUCTION_ACTION_REQUIRED
Example:

"BENEFICIARY_INSTRUCTION_ACTION_REQUIRED"

resource
enum<string>
required

The resource group an event belongs to, sent as the resource field of each delivery body.

Available options:
BENEFICIARY
Example:

"BENEFICIARY"

customerId
string
required

Identifier of the customer the event belongs to.

Example:

"11111111-1111-1111-1111-111111111111"

timestamp
string<date-time>
required

When the event happened, in ISO 8601 UTC. Fixed for the event: retries and replays carry the same value. The time of each delivery attempt is the Webhook-Timestamp header.

Example:

"2026-11-10T14:32:11Z"

data
object
required

Payload delivered for beneficiary payment-instruction lifecycle events (BENEFICIARY_INSTRUCTION_CREATED, BENEFICIARY_INSTRUCTION_APPROVED, BENEFICIARY_INSTRUCTION_REJECTED, BENEFICIARY_INSTRUCTION_ACTION_REQUIRED). Each event corresponds to one payment instruction transition. The payload includes the affected instruction plus enough beneficiary context (id, customerId, entity, relationshipType) to act on the event without an extra lookup. To see the full set of payment instructions attached to a beneficiary, call GET /v1/beneficiaries/{beneficiaryId} on the fx-payment API.

Response

200

Acknowledged. Trace Finance considers any 2xx response a successful delivery.