Subscribe to events

Register webhook endpoints, scope event types, and manage subscriptions.

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 /api/subscriptions request with the URL Trace should call and the resources you want to listen to.

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

The response returns the subscription with its id, the resolved resources (each resource with its full event-type list), and createdAt. Trace 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.

Subscribe to every resource

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/webhook/api/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/webhook/api/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. Fetch the full list of resources and their event types programmatically with GET /references/ResourceName/all.

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 /api/subscriptions — list subscriptions for your customer
• GET /api/subscriptions/{subscriptionId} — fetch one
• PATCH /api/subscriptions/{subscriptionId} — change URL, resources, or allowRetry
• DELETE /api/subscriptions/{subscriptionId} — permanently remove

Update resources or URL

Send PATCH /api/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/webhook/api/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 }.

Related

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