Webhooks

How webhook events, signatures, retries, and delivery handling work in the Numora Public API developer preview.

Scope

This page describes the webhook delivery model used by the Numora Public API developer preview.

Event Types

Supported event types include:

document.processing
document.review_required
document.reviewed
push.succeeded
push.failed
run.failed

Example Event

{
  "id": "evt_01jpx0wq5m6b3m2c9n8r5y2k7p",
  "type": "document.review_required",
  "created_at": "2026-03-21T14:24:11Z",
  "data": {
    "document_id": "doc_01jpwq4q9m7q4q2k8dax1x1q5n",
    "schema": "invoice_v2",
    "status": "review_required"
  }
}

Delivery Headers

Webhook requests should include:

Content-Type: application/json
X-Numora-Webhook-Id: evt_01jpx0wq5m6b3m2c9n8r5y2k7p
X-Numora-Webhook-Timestamp: 2026-03-21T14:24:11Z
X-Numora-Webhook-Signature: t=2026-03-21T14:24:11Z,v1=abcdef123456

Signature Verification

The recommended verification flow is:

Read the raw request body.
Read the delivery timestamp.
Recompute the HMAC signature using the webhook secret.
Compare the computed signature to the received signature.
Reject requests with invalid signatures or stale timestamps.

Retry Behavior

Webhook endpoints should return a 2xx response as soon as the event is durably accepted.

If delivery fails, the platform should retry with backoff. Consumers should design handlers to be idempotent and safe to receive more than once.

Ordering

Consumers should not assume total ordering across all deliveries.

When exact resource state matters more than event sequence, use the webhook as a notification signal and retrieve the latest state from the API.

Handler Recommendations

Verify the signature before parsing the payload into business logic.
Persist the event id to prevent duplicate processing.
Return 2xx quickly and hand off long work to background jobs.
Use the API to refetch the latest resource state when exact freshness matters.

Webhooks

On this page