Webhooks

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:

Stand up an HTTPS endpoint on your side that accepts POST requests.
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 2xx response.
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/v1/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	4	Operation creation, customer action required, completion, and failure
Beneficiary	3	Payment instruction creation, approval, and rejection

Operations publish webhooks on creation (OPERATION_REQUESTED), when paused waiting on your action (OPERATION_CUSTOMER_ACTION_REQUIRED), and on terminal outcomes (OPERATION_COMPLETED, OPERATION_FAILED). The intermediate PROCESSING status is not published — poll GET /v1/operations/{operationId} if you need it.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.

Getting started

Compliance Requirements

API principles

Journeys

Webhooks

Overview

Setup

Signatures

Retry policy

Available events

​Overview

​Setup

​Signatures

​Retry policy

​Available events

Overview

Setup

Signatures

Retry policy

Available events