Webhooks and event delivery

An event announces a change

A notification should identify the run, the observed transition, and the event version. Its arrival is not independent proof that every downstream action succeeded. A receiver should use the run and receipt semantics to decide whether the business contract is fulfilled.

Keep the event envelope small. References to a result and receipt are preferable to repeatedly delivering invoice documents, personal data, or connection details. Retrieving a referenced resource must enforce the caller’s access to that resource.

{
  "sample": true,
  "event_id": "sample_event_001",
  "event_type": "run.state_changed",
  "event_version": "sample-v1",
  "run_id": "sample_run_001",
  "run_revision": 4,
  "state": "reconciling",
  "effect_status": "unknown"
}

Make the receiver tolerant of repetition

1. Authenticate the delivery before trusting the event body. Agree the signing scheme, signed bytes, replay window, and key-rotation procedure as part of the integration contract.
2. Record the event identity durably and accept repeat delivery without duplicating downstream work. A delivery attempt and a business run need different identifiers.
3. Acknowledge after durable acceptance, then process work separately. A successful acknowledgment should mean the receiver retained the event, not that a long business process has finished.
4. Compare revisions or retrieve current run state when events arrive out of order. An older event must not overwrite a later confirmed result.

Signing needs more than a shared secret

A signing scheme needs explicit rules for signed bytes, timestamp handling, replay protection, algorithm selection, key rotation, and constant-time comparison. Parsing and reserializing JSON before checking a signature can change the bytes being authenticated.

Endpoint registration needs its own authorization and network policy. Validate destination schemes and addresses, restrict access to internal services, and make endpoint changes reviewable. An event destination is an integration setting, not an instruction to accept from a document or model response.

Plan for missing deliveries

A receiver outage should not destroy the only record of a run. Provide a reconciliation path from known run identifiers to current state, and record the delivery retention policy alongside retry schedules and replay procedures.

Size the receiver for expected volume and define its recovery window. Include receiver downtime, expired signatures, duplicate events, and delayed delivery in integration tests. An acknowledgment should remain distinct from completion of downstream work.