Events webhooks

Signed incoming status events and their delivery contract.

Graphon Engine sends status events as signed HTTP POST requests to configured receivers. This page defines those incoming requests and their delivery behavior.

Subscription and destination

The operator configures webhook destinations on the cluster. Each destination has a unique name, unique HTTPS url, signing secret, and optional types filter. Loopback development can use HTTP. The API does not expose webhook management routes.

A configured receiver gets the event types in its filter. Omitting types selects all supported types. /info exposes the webhook count and supported event types, without revealing URLs or secrets. New receivers begin with new events; they do not replay historical events.

Request headers

Header	Type	Contract
`Content-Type`	string	`application/json`. Verify the original body bytes before parsing.
`X-Graphon-Events-Signature`	string	`sha256=` followed by the hex HMAC-SHA256 digest.
`X-Graphon-Events-Timestamp`	string containing Unix seconds	The delivery timestamp used in signature verification.
`X-Graphon-Events-Delivery`	string	A del_ identifier unique to this attempt at this webhook.
`X-Graphon-Events-Webhook`	string	The receiver’s configured name.

The signature input is the exact UTF-8 bytes of timestamp + ".", followed by the original HTTP body bytes. Sign with the receiver’s secret using HMAC-SHA256. Prefix the hex digest with sha256=.

Event body

POST to your configured receiver · JSON body

{
  "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",
  "data": {
    "status": "ready",
    "previous_status": "indexing"
  }
}

Field	Type	Contract
`id`	string · required	Stable evt_ ID for this status change. Use it to deduplicate.
`type`	string enum · required	job.updated, file.status_changed, or collection.status_changed.
`occurred_at`	UTC timestamp string · required	Time the resource status changed.
`cluster`	string · required	Cluster name reported by /info.
`namespace`	string or null · required	Namespace associated with the resource, or null when none applies.
`collection`	string or null · required	Collection associated with the resource, or null when none applies.
`job_id`	string or null · required	Related job_ ID, or null when the event has no related job.
`file_id`	string or null · required	Related fil_ ID, or null when the event has no related file.
`data`	object · required	Status transition payload.
`data.status`	string · required	New status for the resource identified by type.
`data.previous_status`	string or null · required	Status before the transition. Null on initial job and file creation.
`data.job_type`	string enum · optional	Operation type for a job event, such as index_file or apply_access_rule.

File states are pending, indexing, ready, failed, and deleting. Job 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.

Within a major API version, new event types or status values can be added. Preserve unknown values without treating them as a known success state.

Responses and delivery

Your response	Engine action
2xx	Delivery succeeds. Engine stops attempts for this event and receiver.
429 or 5xx	Engine retries this receiver.
Network error or timeout	Engine retries this receiver.
3xx	Delivery fails. Engine follows no redirect and does not retry.
Other 4xx	Delivery fails without a retry.

Engine allows 10 seconds per attempt and makes at most eight attempts. Delays after failures are 1, 2, 4, 8, 16, 32, and 64 seconds. A delivery ID is unique per attempt and destination.

Verify timestamps within 300 seconds, then deduplicate event IDs. Delivery retries can repeat an event. Engine delivers events sequentially for each receiver. A retry delays later events for that receiver. One receiver’s failures do not block another.

Recovery

Current resource state remains available through the resource GET endpoints after delivery attempts end. Use Get job, Get file, or Get collection to recover after a missed event.

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

Was this page helpful?