Subscribe to events

Overview

A subscription is the binding between a customer-controlled URL and one or more resources (optionally narrowed to specific event types per resource). You create subscriptions through the Subscriptions API and can have several active at once — typically one per environment.

Create a subscription

Send a POST /v1/subscriptions request with the URL Trace Finance should call and the resources you want to listen to.

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
  }'

The response returns the subscription with its id, the resolved resources (each resource with its full event-type list), and createdAt. Trace Finance begins delivering matching events immediately.

The URL must be HTTPS and reachable from the public internet. Self-signed certificates and private networks are not supported.

Set includeAll: true at the top level to receive every event type from every resource. Useful when you have a single handler that fans out internally.

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",
    "includeAll": true,
    "allowRetry": true
  }'

Scope to specific event types

To narrow delivery for a resource, pass an events array on its SubscriptionResourceRequest instead of includeAll:

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": "BENEFICIARY",
        "events": ["BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED", "BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED"]
      }
    ],
    "allowRetry": true
  }'

Each entry in resources must have a unique name.

Multiple subscriptions

You can register multiple subscriptions — for example, one URL for production and another for staging, or different URLs for different resource subsets. Each subscription is delivered independently; a single event can fan out to several endpoints. There is a per-company limit on active subscriptions.

List, update, and delete

Use the rest of the Subscriptions API to manage existing subscriptions:

GET /v1/subscriptions — list subscriptions for your customer
GET /v1/subscriptions/{subscriptionId} — fetch one
PATCH /v1/subscriptions/{subscriptionId} — change URL, resources, or allowRetry
DELETE /v1/subscriptions/{subscriptionId} — permanently remove

Update resources or URL

Send PATCH /v1/subscriptions/{subscriptionId} with only the fields you want to change. To replace the resource list, pass a new resources array — it overwrites the existing set.

curl --request PATCH \
  --url https://api.sandbox.tracefinance.com/v1/subscriptions/<subscription-id> \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "resources": [
      { "name": "OPERATION", "includeAll": true },
      { "name": "BENEFICIARY", "events": ["BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED"] }
    ]
  }'

To stop retrying failed deliveries without removing the subscription, send { "allowRetry": false }.

Verify signatures — confirm requests came from Trace Finance
Retry policy — understand what happens when your endpoint is down
Test in sandbox — drive events for development

Getting started

Compliance Requirements

API principles

Webhooks

Journeys

Overview

Create a subscription

Scope to specific event types

Multiple subscriptions

List, update, and delete

Update resources or URL

​Overview

​Create a subscription

​Subscribe to every resource

​Scope to specific event types

​Multiple subscriptions

​List, update, and delete

​Update resources or URL

​Related

Overview

Create a subscription

Subscribe to every resource

Scope to specific event types

Multiple subscriptions

List, update, and delete

Update resources or URL

Related