Skip to main content

Create Config

Create a webhook configuration with a destination URL, event subscriptions, optional signing secret, and optional source scoping.

Create a new webhook configuration to receive event notifications at a specified URL. Provide the destination URL and optionally specify which events to subscribe to, a signing secret for HMAC verification, and a source connection to scope the webhook.

If no events array is provided, the webhook defaults to subscribing to extraction.complete and extraction.failed. If no secret is provided, an empty string is used — you should always set a secret in production to enable signature verification of incoming payloads.

The source_connection_id field scopes the webhook to events from a specific source. When omitted or null, the webhook fires for events from all sources. This is useful when different sources should route to different backend systems.

After creation, test your webhook by triggering an extraction. The webhook will fire within seconds of the event occurring. Use the Signature Verification guide to validate incoming payloads and the Retry Policy reference to understand delivery guarantees.

Always set a secret in production. Without a secret, you cannot verify that incoming webhook payloads are authentic. The secret is used to compute the HMAC-SHA256 signature sent in the X-Talonic-Signature header.
POST/v1/webhooks

Response

Response (201 Created)

{
  "id": "wh_b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "url": "https://api.example.com/webhooks/talonic",
  "events": ["extraction.complete", "extraction.failed", "document.ingested"],
  "is_active": true,
  "source_connection_id": null,
  "created_at": "2024-10-05T12:00:00.000Z",
  "updated_at": "2024-10-05T12:00:00.000Z",
  "links": {
    "self": "/v1/webhooks/wh_b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}

Errors

Error responses

400validation_errorMissing required url field or invalid URL format.
401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

List Configs
Signature Verification