Delivery Format

Talonic webhooks are HTTP POST requests with a JSON body and headers for event type, HMAC signature, and delivery ID. See the exact request format and headers.

Every Talonic webhook is delivered as an HTTP POST request with an application/json body containing four top-level fields: event (the event type), delivery_id (unique per delivery), timestamp (ISO 8601), and data (the event-specific payload). Configure webhook URLs workspace-wide or per-source via [webhook configurations](list-webhook-configs), or per-extraction via the webhook_url option on POST /v1/extract.

Each delivery carries these headers: Content-Type: application/json, X-Talonic-Event (the event type, useful for routing), X-Talonic-Delivery (unique delivery ID for idempotency), User-Agent: Talonic-Webhooks/1.0, and, when a signing secret is configured, X-Talonic-Signature (HMAC-SHA256 of the raw body). Your endpoint must return a 2xx status within 30 seconds or the attempt is considered failed and retried.

POST /webhooks/talonic HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Talonic-Event: extraction.complete
X-Talonic-Delivery: dlv_a1b2c3d4e5f67890
X-Talonic-Signature: sha256=9832313c4adcbe269b8b7c11c1855f6d437f2089a15aa22ebd9f21d356d062ed
User-Agent: Talonic-Webhooks/1.0

{
  "event": "extraction.complete",
  "delivery_id": "dlv_a1b2c3d4e5f67890",
  "timestamp": "2026-01-15T10:00:00.000Z",
  "data": {
    "document_id": "3d44a4dc-e3e4-4bca-b079-a9c85bf75026",
    "extraction_id": "3d44a4dc-e3e4-4bca-b079-a9c85bf75026",
    "filename": "invoice.pdf",
    "field_count": 12,
    "confidence_overall": 0.92
  }
}

Most integrations configure a single webhook endpoint that handles all event types, using the X-Talonic-Event header to route internally. A typical setup is one persistent webhook configuration for extraction.complete and extraction.failed, plus ad-hoc webhook_url overrides on POST /v1/extract for request-specific callbacks.

app.post('/webhooks/talonic', express.raw({ type: 'application/json' }), (req, res) => {
  res.status(200).send('ok'); // acknowledge first

  switch (req.headers['x-talonic-event']) {
    case 'extraction.complete': return onExtraction(JSON.parse(req.body).data);
    case 'run.completed':       return onRunCompleted(JSON.parse(req.body).data);
    case 'app.action.execute':  return onAppAction(JSON.parse(req.body).data);
    default:                    return; // ignore unhandled event types
  }
});

Delivery is a fan-out: each event enqueues one delivery per matching target — every active configuration subscribed to the event type (workspace-wide or scoped to the originating source), plus any per-request webhook_url override. Each target gets its own delivery ID and its own retry ladder, so a failure at one endpoint never delays another. If no target matches, zero deliveries are enqueued for that event.

Pair the delivery format with the [Signature Verification](webhook-security) guide to authenticate incoming payloads, and see the [Retry Policy](webhook-retry) for the backoff schedule applied to failed deliveries. The full format is also available machine-readably at GET /v1/webhooks/delivery.