Skip to main content

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 Finance POSTs a JSON payload whenever a relevant event fires. A typical integration looks like:
  1. Stand up an HTTPS endpoint on your side that accepts POST requests.
  2. Register the URL with the Subscriptions API, choosing the resource and event types you want.
  3. Verify each request’s signature, process the payload, and return a 2xx response.
  4. 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.
See Subscribe to events for the full setup walkthrough — including how to manage multiple subscriptions, scope event types, and pause delivery.

Delivery format

Deliveries follow the Standard Webhooks specification: three Webhook-* headers and a JSON body that carries the event metadata at the top level and the event itself in data.
This format is live in sandbox. Production switches to it on a date Trace Finance announces to integrators; until then, production keeps sending the previous format. See Migrating from the previous format.
The 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

The Webhook-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 in X-* headers. Each of them maps to the new format: To move a handler over:
  1. Verify Webhook-Signature over the raw body. X-Message-Signature is not sent in the new format.
  2. Read type, resource and customerId from the body instead of the headers, and the event object from data.
  3. Deduplicate on Webhook-Id.
X-Message-Id repeated across different events of the same resource: one operation’s OPERATION_REQUESTED, OPERATION_PROCESSING and OPERATION_COMPLETED all carried the same value. Webhook-Id is unique per event and repeats only when the same event is retried or replayed. If your handler deduplicated on X-Message-Id, switch it to Webhook-Id, not to the resource id in data: keying on the resource drops every later event of that resource.