Skip to main content
POST

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 Finance 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
​
allowRetry
boolean
default:false

Whether failed deliveries should be retried. Defaults to false.

Response

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.

​
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"