> ## Documentation Index > Fetch the complete documentation index at: https://docs.tracefinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a subscription > Register a webhook subscription for a resource. ## OpenAPI ````yaml apis/fx-webhook/openapi.yml POST /v1/subscriptions openapi: 3.1.1 info: title: Trace Finance Webhooks API version: 1.0.0 description: > API for managing webhook subscriptions and inspecting webhook delivery history on the Trace Finance platform. servers: - url: https://api.sandbox.tracefinance.com description: Sandbox security: - bearerAuth: [] tags: - name: Subscriptions description: Create, list, update, and delete webhook subscriptions. - name: Execution logs description: Inspect webhook delivery attempts and resend failed deliveries. - name: References description: Look up the resources and event types available for subscription. paths: /v1/subscriptions: post: tags: - Subscriptions summary: Create a subscription description: >- Register a webhook subscription for a resource. Trace Finance will POST events to the supplied URL. operationId: createSubscription parameters: - $ref: '#/components/parameters/TraceVersion' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionRequest' examples: all-events: summary: Subscribe to every resource and event type value: url: https://api.example.com/trace-webhooks includeAll: true allowRetry: true specific-resource: summary: Subscribe to all OPERATION events value: url: https://api.example.com/trace-webhooks resources: - name: OPERATION includeAll: true allowRetry: true specific-events: summary: Subscribe only to selected beneficiary events value: url: https://api.example.com/trace-webhooks resources: - name: BENEFICIARY events: - BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED - BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED allowRetry: true responses: '201': description: Subscription created. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Subscription' '400': description: Validation error. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/UnauthorizedError' components: parameters: TraceVersion: name: X-Trace-Version in: header required: false description: API version. Omit to use the default version. schema: type: string example: '1' IdempotencyKey: name: X-Idempotency-Key in: header required: true description: >- Unique key to ensure idempotent request processing. Required on all `POST`, `PUT`, and `PATCH` requests. schema: type: string format: uuid schemas: CreateSubscriptionRequest: type: object description: Request body for creating a new webhook subscription. properties: url: type: string format: uri description: >- HTTPS URL where Trace Finance will POST event payloads. Must be reachable from the public internet. example: https://api.example.com/trace-webhooks includeAll: type: boolean description: >- When `true`, the subscription is created for every resource and event type, and the `resources` field is ignored. Defaults to `false`. default: false resources: type: array description: >- Resources the subscription should listen to. Required when `includeAll` is `false`. Each resource name must be unique. minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/SubscriptionResourceRequest' allowRetry: type: boolean description: Whether failed deliveries should be retried. Defaults to `false`. default: false required: - url Subscription: type: object description: >- A webhook subscription that delivers events from one or more resources to a customer-controlled URL. properties: id: type: string format: uuid example: 8a13c6a4-1a3d-4f49-ad62-9dca8c47e2c6 readOnly: true companyId: type: string description: Company identifier that owns the subscription. example: 11111111-1111-1111-1111-111111111111 url: type: string format: uri example: https://api.example.com/trace-webhooks resources: type: array description: Resources and event types this subscription delivers. items: $ref: '#/components/schemas/SubscriptionResource' allowRetry: type: boolean description: Whether failed deliveries are retried. example: true createdAt: type: string format: date-time example: '2026-04-28T14:32:11Z' readOnly: true updatedAt: type: string format: date-time example: '2026-04-28T14:32:11Z' readOnly: true required: - id - companyId - url - resources - allowRetry - createdAt - updatedAt ErrorResponse: type: object description: >- Standard error response. See the [Errors](/guides/principles/errors) guide for the full code catalog. properties: code: type: string example: RESOURCE_NOT_FOUND message: type: string example: >- Subscription with id '8a13c6a4-1a3d-4f49-ad62-9dca8c47e2c6' was not found. details: type: object additionalProperties: true required: - code - message SubscriptionResourceRequest: type: object description: >- A resource the subscription should listen to, optionally narrowed to specific event types. properties: name: $ref: '#/components/schemas/ResourceName' includeAll: type: boolean description: >- When `true`, the subscription receives every event type under this resource and the `events` field is ignored. Defaults to `false`. default: false events: type: array description: >- Specific event types to receive. Required when `includeAll` is `false`. items: $ref: '#/components/schemas/EventType' example: - BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED - BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED required: - name SubscriptionResource: type: object description: >- A resource the subscription delivers events for, with the chosen event types resolved. properties: name: $ref: '#/components/schemas/ResourceName' events: type: array items: $ref: '#/components/schemas/EventType' required: - name - events ResourceName: type: string description: The resource group an event belongs to. enum: - ACCOUNT - BENEFICIARY - OPERATION example: OPERATION EventType: type: string description: >- The specific event type within a resource, sent as the `X-Event-Type` header on each delivery. enum: - ACCOUNT_CREATED - ACCOUNT_ACTION_REQUIRED - ACCOUNT_ASSET_ACTIVATED - ACCOUNT_ASSET_FAILED - BENEFICIARY_PAYMENT_INSTRUCTION_CREATED - BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED - BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED - OPERATION_REQUESTED - OPERATION_COMPLETED - OPERATION_FAILED - OPERATION_CUSTOMER_ACTION_REQUIRED example: OPERATION_REQUESTED headers: RequestId: description: >- Unique request identifier emitted on every response. Reference it when contacting Trace Finance support so we can trace the request end-to-end. See [Errors](/guides/principles/errors). schema: type: string format: uuid responses: UnauthorizedError: description: Missing or invalid authentication token. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token. Include as `Authorization: Bearer `. See the [Authentication](/guides/authentication) guide for how to obtain one. ````