Webhook Design

Webhooks are HTTP callbacks that notify external systems of events in real time, inverting the typical request-response pattern. Instead of consumers polling for changes, the server POSTs event payloads to URLs registered by the consumer. Common webhook events include payment.completed, order.shipped, or user.created. The webhook payload typically includes the event type, a timestamp, the affected resource ID, and often a snapshot of the resource's current state.

Robust webhook design requires several considerations: payloads should include an event type and version so consumers can handle schema evolution; a unique event ID enables idempotent processing on the consumer side; and a signature header (typically HMAC-SHA256 of the payload using a shared secret) allows consumers to verify the webhook came from the expected source and wasn't tampered with. Events should be sent asynchronously via a background job queue, not in the request path, to avoid blocking the originating operation.

The webhook system needs a management API where consumers can register endpoint URLs, select which event types they want to receive, and manage their signing secrets. A webhook logs dashboard showing recent deliveries, response codes, and payloads is essential for debugging. Failed deliveries should be retried with exponential backoff, and endpoints that consistently fail should be automatically disabled after a threshold with notification to the consumer.