Overview
Webhooks let Trace Finance push events to your backend as they happen — account onboarding completions, beneficiary review outcomes, payment operation updates, and more. Instead of polling for state changes, you register an HTTPS endpoint and Trace FinancePOSTs a JSON payload whenever a relevant event fires.
A typical integration looks like:
- Stand up an HTTPS endpoint on your side that accepts
POSTrequests. - Register the URL with the Subscriptions API, choosing the resource and event types you want.
- Verify each request’s signature, process the payload, and return a
2xxresponse. - Trace Finance retries failed deliveries and exposes execution logs for inspection and manual replay.
Setup
Webhook subscriptions are managed through the Subscriptions API. Each subscription binds one URL to one or more resources (ACCOUNT, OPERATION, BENEFICIARY) and optionally narrows delivery to specific event types per resource.
Delivery format
Deliveries follow the Standard Webhooks specification: threeWebhook-* headers and a JSON body that carries the event metadata at the top level and the event itself in data.
data object above is shortened; each event’s full schema is in the event catalog.
Requests can also carry tracing headers such as
X-Correlation-Id, traceparent and tracestate. They are not part of the contract and are not signed, so ignore them. The body is identical on every retry and replay:
Signatures
TheWebhook-Signature header holds a v1,<base64> HMAC-SHA256 over {Webhook-Id}.{Webhook-Timestamp}.{raw body}, with your client secret as the key. The raw body is the whole JSON above, so the signature also covers type, resource and customerId.
See Verify signatures for verification code in Python, JavaScript, and Go.
Retry policy
If your endpoint returns a non-2xx status or fails to respond, Trace Finance queues the delivery for retry with a delay between attempts. Each delivery attempt is recorded in an execution log you can inspect or resend manually.
See Retry policy for the exact retry budget, log lifetime, and replay guidance.
Available events
Browse the full event catalog by resource:Operations publish webhooks on creation (
OPERATION_REQUESTED),
when execution starts (OPERATION_PROCESSING), when paused waiting
on your action (OPERATION_ACTION_REQUIRED), and on terminal
outcomes (OPERATION_COMPLETED, OPERATION_FAILED). A refund is
announced at both ends: OPERATION_REFUNDING when you ask for it,
OPERATION_REFUNDED when the money is back with the payer.Accounts publish ACCOUNT_CREATED, ACCOUNT_ACTION_REQUIRED,
ACCOUNT_ASSET_ACTIVATED, and ACCOUNT_ASSET_FAILED. Other account
state transitions are not published — poll
GET /v1/accounts/{accountId} if you need them.Migrating from the previous format
The previous format sent the event object as the whole body and the event metadata inX-* headers. Each of them maps to the new format:
To move a handler over:
- Verify
Webhook-Signatureover the raw body.X-Message-Signatureis not sent in the new format. - Read
type,resourceandcustomerIdfrom the body instead of the headers, and the event object fromdata. - Deduplicate on
Webhook-Id.