Create Webhook Config

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

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-SHA256 verification, and a source connection to scope the webhook. The configuration is live immediately: the next matching event triggers a delivery.

If no events array is provided, the webhook defaults to subscribing to extraction.complete and extraction.failed. If no secret is provided, deliveries are sent unsigned (no X-Talonic-Signature header). Always set a secret in production so you can verify that incoming payloads are authentic.

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 fires within seconds of the event occurring. Use the [Signature Verification](webhook-security) guide to validate incoming payloads and the [Retry Policy](webhook-retry) reference to understand delivery guarantees.

{
  "url": "https://api.example.com/webhooks/talonic",
  "secret": "whsec_my_production_secret",
  "events": ["extraction.complete", "extraction.failed", "document.uploaded"],
  "is_active": true
}

Response

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "url": "https://api.example.com/webhooks/talonic",
  "events": ["extraction.complete", "extraction.failed", "document.uploaded"],
  "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/b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}

Errors