Webhooks

Webhooks push real-time notifications when events occur in your Talonic workspace. All payloads are HMAC-SHA256 signed using the signing secret configured on your delivery destination, ensuring authenticity and tamper detection. Failed deliveries retry with exponential backoff — the platform makes progressively spaced attempts before routing terminal failures to the dead-letter queue (DLQ) for manual replay.

The webhook connector is configured as a delivery destination. Bind any of the event types below to a webhook destination to receive real-time notifications. See /v1/delivery/catalog/signals for the exhaustive list (the catalog API refers to events as *signals*).

When a webhook fires, the platform constructs the payload from the event data, signs it with your destination's HMAC-SHA256 signing secret, and delivers it via HTTPS POST. Each delivery includes an idempotency key in the headers so your receiver can safely deduplicate retries. Failed deliveries follow an exponential backoff schedule, and terminal failures are routed to the dead-letter queue for manual replay.

Use webhooks when your downstream system needs to react immediately to platform events — for example, triggering an ERP import when a document is extracted, or notifying a Slack channel when a reviewer rejects a record. For bulk or periodic data transfers, consider using the SFTP, S3, or cloud storage delivery connectors instead.

To set up a webhook, create a delivery destination of type webhook with your endpoint URL and a signing secret. Then create a binding that maps one or more event types to the destination. When an event fires, the platform constructs the payload, signs it, and delivers it to your endpoint. You can bind multiple event types to the same destination or spread them across different destinations for different downstream systems.

• HMAC-SHA256 signed payloads for authenticity and tamper detection
• Idempotency key in headers for safe deduplication on retries
• Exponential backoff on delivery failure with configurable retry limits
• Dead-letter queue (DLQ) for terminal failures with manual replay
• Bind any event type to a webhook destination via delivery bindings
• 11 core event types covering document, run, result, and delivery lifecycle events, plus run.*.failed counterparts
• Meta-events (delivery.item.completed/failed) are not re-delivered to avoid loops

Setting Up Webhooks via API

Webhooks are configured through the delivery API. First create a destination of type webhook with your endpoint URL and signing secret, then create a binding that maps event types to the destination. You can bind multiple event types to the same destination or use separate destinations for different event categories. The delivery catalog endpoint lists all available event types so you can choose which events to subscribe to.

curl https://api.talonic.com/v1/delivery/catalog/signals \
  -H "Authorization: Bearer $TALONIC_API_KEY"

// Your endpoint receives:
// Header: X-Talonic-Signature: t=1714060200000,v1=abc123...
// Body:   {"type":"document.extracted","data":{...}}

const crypto = require('crypto');
const [tPart, vPart] = signature.split(',');
const timestamp = tPart.split('=')[1];
const received  = vPart.split('=')[1];
const expected  = crypto
  .createHmac('sha256', SIGNING_SECRET)
  .update(timestamp + '.' + rawBody)
  .digest('hex');
const valid = crypto.timingSafeEqual(
  Buffer.from(received), Buffer.from(expected));

For high-reliability integrations, always verify the HMAC-SHA256 signature before processing webhook payloads. The X-Talonic-Signature header carries a timestamp (t=) and a hex digest (v1=); compute the HMAC of timestamp + "." + rawBody using your signing secret and compare it to v1 with a timing-safe comparison. This verification confirms that the payload was sent by Talonic and has not been tampered with in transit. Additionally, use the idempotency key header to deduplicate retried deliveries — store processed idempotency keys and skip any payload you have already handled.