Webhooks

Receive real-time event notifications from the Trace Finance platform.

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.

curl --request POST \
  --url https://api.sandbox.tracefinance.com/webhook/api/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://api.example.com/trace-webhooks",
    "resources": [
      { "name": "OPERATION", "includeAll": true }
    ],
    "allowRetry": true
  }'

See Subscribe to events for the full setup walkthrough — including how to manage multiple subscriptions, scope event types, and pause delivery.

Signatures

Every outbound request carries a X-Message-Signature header containing an HMAC-SHA256 signature you use to verify the message came from Trace Finance. The signature is computed over ${messageId}+${clientId} with your client secret as the key:

X-Message-Signature: <hex-encoded HMAC-SHA256 of "messageId+clientId">

Other headers you can rely on:

Header	Purpose
X-Message-Id	Unique delivery identifier — also a UUID for idempotency on your side
X-Company-Id	Your Trace Finance company identifier
X-Event-Type	Event type (e.g., OPERATION_REQUESTED)
X-Resource-Name	Resource group (e.g., OPERATION)

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:

Resource	Events	Description
Account	4	Account creation, action-required transitions, and asset onboarding outcomes
Operation	3	Operation creation, completion, and failure
Beneficiary	3	Payment instruction creation, approval, and rejection

You can also fetch the catalog programmatically: GET /references/ResourceName/all.

Operations publish webhooks on creation (OPERATION_REQUESTED) and on terminal outcomes (OPERATION_COMPLETED, OPERATION_FAILED). Intermediate statuses (PROCESSING, ON_HOLD, ACTION_REQUIRED) are not published — poll GET /api/operations/{operationId} if you need them.

Accounts publish ACCOUNT_CREATED, ACCOUNT_ACTION_REQUIRED, ACCOUNT_ASSET_ACTIVATED, and ACCOUNT_ASSET_FAILED. Other account state transitions are not published — poll GET /api/accounts/{accountId} if you need them.