Events & webhook delivery

Subscribe to meaningful changes#

Register a verified public HTTPS endpoint and select enabled event types. Subscriptions and replay obey your integration’s current resource policy.

Events carry resource references and minimal state. Fetch the authorized resource for the latest details; raw documents and internal notes do not belong in event payloads.

{
  "id": "evt_example",
  "type": "case.action_required",
  "schemaVersion": "1",
  "resource": { "type": "case", "id": "case_example", "version": "17" },
  "data": { "reason": "additional_information" }
}

Verify before accepting#

Webhook signing uses HMAC-SHA256 over timestamp + "." + the raw body bytes. Verify the signature with the subscription secret and check a bounded timestamp freshness window before parsing or accepting work.

Use the signing configuration supplied with your webhook subscription. Retried deliveries retain the event ID but receive a fresh timestamp and signature.

Assume duplicates and out-of-order arrival#

• Persist receipt before acknowledging with 2xx, then process asynchronously.
• Deduplicate by event ID. A transport retry must not perform the business action twice.
• Compare resource versions. An older event must not overwrite a newer local state.
• Do not assume ordering across different resources or subscriptions.

Recover through the event log#

Retain a cursor from GET /tenant/events. After an outage, replay changes from that cursor and reconcile affected resources.

Event retention and delivery retry windows follow your environment policy. A cursor outside retention returns 410 cursor_expired and requires a full resynchronization.