Reference Endpoints

Read the webhook event catalog, delivery payload format, HMAC signature scheme, and retry policy programmatically via four read-only reference endpoints.

The webhook reference endpoints expose the event catalog, delivery format, signature scheme, and retry policy as live read-only JSON, so an integration can discover them at runtime instead of hard-coding them. Each returns the same reference information described in the sections above, and all four require only an API key with read scope.

The most useful of the four is GET /v1/webhooks/events: it is the authoritative catalog of event types your key can subscribe to, including newer families such as the app.* App-lifecycle events. Fetching it at integration time (or in CI) protects you from typos in the events array of a webhook configuration and surfaces newly added event types without a docs check.

The delivery and signatures endpoints describe the request your endpoint will receive: content type, HTTP method, headers (including X-Talonic-Event, X-Talonic-Delivery, and the conditional X-Talonic-Signature), the four-field body envelope, and the exact HMAC-SHA256 verification steps. Use them to generate handler scaffolding or to validate your implementation against the live contract.

These endpoints are versioned with the API itself, so their responses change only when webhook behaviour changes. A reasonable pattern is to snapshot the responses in your test fixtures and diff them in CI — a changed snapshot is an early signal that a new event type or header is available.

curl https://api.talonic.com/v1/webhooks/events \
  -H "Authorization: Bearer tlnc_your_api_key"

{
  "data": [
    { "event": "app.run.completed", "description": "An App run reached a sealed decision record." },
    { "event": "app.action.execute", "description": "An App decision executes an action; the payload carries the decision, evidence, and idempotency key." },
    { "event": "document.uploaded", "description": "A new document has been uploaded and queued for processing." },
    { "event": "extraction.complete", "description": "Data extraction finished successfully. Extracted fields are available." },
    { "event": "run.completed", "description": "A /v1/run pipeline finished; structured output is available (review-held fields null). ..." }
  ]
}

curl https://api.talonic.com/v1/webhooks/signatures \
  -H "Authorization: Bearer tlnc_your_api_key"

{
  "algorithm": "HMAC-SHA256",
  "header": "X-Talonic-Signature",
  "format": "sha256={hex_digest}",
  "signed_content": "The raw JSON request body (UTF-8 encoded)",
  "verification_steps": [
    "1. Read the raw request body as a UTF-8 string (do not parse JSON first).",
    "2. Compute HMAC-SHA256 of the body using your webhook signing secret.",
    "3. Hex-encode the digest.",
    "4. Compare with the value after \"sha256=\" in the X-Talonic-Signature header.",
    "5. Use constant-time comparison to prevent timing attacks."
  ]
}