Receive and process webhooks

Subscribe to the events you need

Use webhooks to notify another system about relevant operational changes. Start with the smallest event set needed for the handoff, such as changes that affect receiving, review, or completion. Confirm the exact event names and schemas in your workspace’s event catalog.

Define whether the event includes sufficient state to process independently or requires an authorized follow-up read. Event occurrence time, delivery time, and processing time are different facts.

Authenticate and durably accept the event

1. Receive the request over HTTPS and preserve the raw body needed by the documented verification method.
2. Verify authenticity and replay protections before trusting the payload.
3. Validate the supported event schema and intended workspace.
4. Record the event identity in a durable inbox with a unique constraint.
5. Acknowledge only after the event is durably accepted, then process it asynchronously.

Design for retries and out-of-order arrival

Delivery can be repeated or delayed. Deduplicate by the stable event identity and make the downstream effect idempotent. A unique inbox record alone does not protect an external side effect if the worker crashes after making it.

Use the documented record revision or ordering information to detect older events. Where necessary, retrieve current authorized state and reconcile. Do not assume arrival order proves business order.

verifyDelivery(rawBody, headers, deliveryContract)
event = validateSupportedEvent(rawBody)

transaction:
  insertInboxIfAbsent(event.identity, event.payload)

acknowledgeAccepted()

worker:
  claimPendingEvent()
  applyEffectIdempotently()
  recordOutcomeOrScheduleRetry()

Make recovery observable

• Monitor pending events, oldest unprocessed age, failures, and retry counts.
• Quarantine unsupported or invalid events with enough context to investigate.
• Keep secrets and unnecessary sensitive payloads out of routine logs.
• Test duplicate delivery, unavailable receivers, worker crashes, and replay before launch.