Create a subscription

Register a webhook subscription for a resource.

POST /api/subscriptions

cURL

all-events

curl --request POST \ --url https://api.sandbox.tracefinance.com/api/subscriptions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'X-Idempotency-Key: <x-idempotency-key>' \ --data ' { "url": "https://api.example.com/trace-webhooks", "includeAll": true, "allowRetry": true } '

201

{
  "id": "8a13c6a4-1a3d-4f49-ad62-9dca8c47e2c6",
  "companyId": "11111111-1111-1111-1111-111111111111",
  "url": "https://api.example.com/trace-webhooks",
  "resources": [
    {
      "name": "OPERATION",
      "events": [
        "OPERATION_REQUESTED"
      ]
    }
  ],
  "allowRetry": true,
  "createdAt": "2026-04-28T14:32:11Z",
  "updatedAt": "2026-04-28T14:32:11Z"
}

Authorizations

Authorization · string · header · required

JWT bearer token. Include as Authorization: Bearer <token>. See the Authentication guide for how to obtain one.

Headers

X-Trace-Version · string

API version. Omit to use the default version.

Example:

"1"

X-Idempotency-Key · string<uuid> · required

Unique key to ensure idempotent request processing. Required on all POST, PUT, and PATCH requests.

Body

application/json

Request body for creating a new webhook subscription.

url · string<uri> · required

HTTPS URL where Trace will POST event payloads. Must be reachable from the public internet.

Example:

"https://api.example.com/trace-webhooks"

includeAll · boolean · default: false

When true, the subscription is created for every resource and event type, and the resources field is ignored. Defaults to false.

resources · object[]

Resources the subscription should listen to. Required when includeAll is false. Each resource name must be unique.

Minimum array length: 1

Show child attributes

allowRetry · boolean · default: false

Whether failed deliveries should be retried. Defaults to false.

Response

201

application/json

Subscription created.

A webhook subscription that delivers events from one or more resources to a customer-controlled URL.

id · string<uuid> · required · read-only

Example:

"8a13c6a4-1a3d-4f49-ad62-9dca8c47e2c6"

companyId · string · required

Company identifier that owns the subscription.

Example:

"11111111-1111-1111-1111-111111111111"

url · string<uri> · required

Example:

"https://api.example.com/trace-webhooks"

resources · object[] · required

Resources and event types this subscription delivers.

Show child attributes

allowRetry · boolean · required

Whether failed deliveries are retried.

Example:

true

createdAt · string<date-time> · required · read-only

Example:

"2026-04-28T14:32:11Z"

updatedAt · string<date-time> · required · read-only

Example:

"2026-04-28T14:32:11Z"