Webhooks

Receive resource events with signature verification and safe redelivery handling.

Event envelope#

A subscription delivers a JSON envelope with a stable event ID, event type, timestamp, and resource reference. Fetch the current resource from the API when your workflow needs a complete representation.

{
  "id": "evt_example_024",
  "type": "service.deployment.completed",
  "occurredAt": "2026-10-15T10:00:00Z",
  "resource": {"project": "catalog", "service": "catalog"},
  "data": {"revision": "rev-024", "status": "ready"}
}

Verify before processing#

Verify the request signature against the raw request body using your subscription’s signing secret. Reject timestamps outside a short acceptance window. Compare signatures with a constant-time operation.

Handle duplicate deliveries#

Delivery is at least once. Store the event ID as an idempotency marker, acknowledge accepted events quickly, and process longer work asynchronously. Non-2xx responses trigger bounded redelivery with increasing delays.

Response	Delivery behavior
200–299	Acknowledged
400–499	Recorded as rejected; investigate receiver configuration
500–599 or timeout	Retried within the subscription delivery window