Events webhooks

Webhooks and scopes

A key registers a webhook with Create webhook: a unique name, a scope, an HTTPS url, and optional types. The webhook gets each event in its scope whose type is in types. Null or omitted types selects every type, also types added later.

A new webhook gets only the events that occur after its create. Replay webhook deliveries queues earlier events while Engine still holds them (30 days). /info reports the number of webhooks that the calling key can see, and the supported event types.

The URL must use https, hold no user info or fragment, and resolve only to public addresses. Engine checks the address again on every connection, follows no redirect, and never reads the response body.

Engine takes no webhooks from the cluster configuration. A configuration that sets events.webhooks, also to an empty list, fails GET /ready with details.failed: ["events"].

Request headers

The secret is whsec_ and the base64 of 32 random bytes. The HMAC key is the decoded bytes. The signed content is the exact UTF-8 bytes of webhook-id + "." + webhook-timestamp + ".", followed by the original HTTP body bytes. It covers the whole batch. Each signature is v1, and the base64 HMAC-SHA256 digest. During a rotation overlap, Engine signs with the new and the previous secret, newest first. Accept the POST when one signature matches.

Event body

{
  "events": [
    {
      "id": "evt_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
      "type": "file.status_changed",
      "occurred_at": "2026-10-06T12:01:00Z",
      "cluster": "graphon-engine",
      "namespace": "acme",
      "collection": "incident-logs",
      "job_id": "job_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
      "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
      "research_id": null,
      "data": {
        "status": "ready",
        "previous_status": "indexing"
      }
    }
  ]
}

The body is {"events": [...]}: the webhook’s oldest queued events, up to 500 events or 1 MiB. One larger event goes alone. Each event has the fields below.

File states are pending, indexing, ready, failed, and deleting. File stages, in order, are engine_queued, checking_source, core_queued, processing, and building_index. Only an indexing file has a stage. Job and research states are queued, running, succeeded, failed, and canceled. Collection states are empty, indexing, ready, degraded, failed, and deleting. Creating an empty collection does not emit a collection event.

webhook.test comes only from Test webhook. It is a batch of one event whose namespace, collection, and IDs are null. It is not queued, never retried, and not in the delivery log.

{
  "events": [
    {
      "id": "evt_01J8Z3K4N5P6Q7R8S9T0V1W2X6",
      "type": "webhook.test",
      "occurred_at": "2026-10-06T12:00:00Z",
      "cluster": "graphon-engine",
      "namespace": null,
      "collection": null,
      "job_id": null,
      "file_id": null,
      "research_id": null,
      "data": {
        "webhook": "acme-status"
      }
    }
  ]
}

Within a major API version, new event types or status values can be added. Ignore an event type that you do not know, and answer 2xx. Preserve unknown values without treating them as a known success state.

Responses and delivery

Your response applies to the whole batch. Engine allows 30 seconds per POST. A retry sends the same bytes with the same webhook-id. A batch retries until the receiver answers or the webhook turns off. A failed event is not sent again unless a key replays it.

Engine sends one batch at a time to each webhook, in order. A retry delays only the later events of that webhook. One webhook’s failures never block another.

After a failed attempt, a webhook older than 72 hours with no 2xx in the last 72 hours turns off with disabled_reason failing. A 410 turns it off at once. Turning a webhook off ends its queued events failed. A key turns it on again with Update webhook, and the webhook then gets only new events.

Delivery log and replay

Each webhook keeps 30 days of deliveries and attempts. A key with read on part of a wider webhook sees only the deliveries of its own namespace or collections. Replay queues past events again, by ID or by time range, when they are in the webhook’s scope and types and Engine still holds them. A replayed event keeps its id and its bytes, in a new batch. A replay on a disabled webhook returns 409 webhook_disabled.

Recovery

Use List webhook deliveries to find what a receiver missed, and Replay webhook deliveries to send it again. Current resource state also stays available through the resource GET endpoints. Use Get job, Get file, Get collection, or Get research for a gap older than 30 days.

The jobs and events guide includes receiver setup, verification code, and an acknowledgement workflow.