Before you start
Webhook delivery is at-least-once. Your receiver must be idempotent and must verify signatures before parsing or processing payloads.
Delivery model
Each event delivery has a stable event ID, endpoint target, retry count, outcome, and trace/correlation context. Delivery attempts should be logged with the Workspace, Project, environment, event type, response status, and processing result.
Retry behavior
Lamba retries non-2xx responses. Your receiver should return 2xx only after durable acceptance. If processing is slow, persist the event first, enqueue local work, and acknowledge only after the event is safe.
Idempotency
Store the event ID before side effects.
receive request
verify timestamp freshness
verify HMAC signature
deduplicate by event id
persist event
process side effect
return 204
Operational logs
Log these fields:
- event ID
- event type
- endpoint ID
- Workspace and Project scope
- environment
- retry count
- response status
- processing outcome
- trace or correlation ID
Test deliveries
Use test delivery in sandbox before production rollout. Test the success path, invalid signature path, duplicate event path, and transient failure path.
Related docs
- Webhooks Integration:
/docs/quickstart/webhooks - Webhook Events:
/docs/reference/webhook-events - Webhook Signature Verification:
/docs/reference/webhook-signatures