A webhook is an HTTP request sent automatically from one system to another when an event occurs. The receiver registers a URL, and the sender calls that URL after events such as payment succeeded, commit pushed, form submitted, or user created.
Webhooks are push based integration. The receiver does not poll repeatedly to discover changes. The sender pushes an event when it has something to report.
Request flow
sequenceDiagram participant Source participant Receiver Source->>Receiver: POST event payload Receiver->>Receiver: Verify signature Receiver->>Receiver: Store event ID Receiver-->>Source: 2xx accepted Receiver->>Receiver: Process asynchronously
Good receivers acknowledge quickly, then process the work asynchronously. The sender should not wait while the receiver performs slow business work.
Webhook contract
A useful webhook contract defines more than a URL.
- Event name and version.
- Stable event ID for idempotency.
- Timestamp and source account or tenant.
- Signature scheme and secret rotation process.
- Retry policy and timeout expectations.
- Payload examples for success, failure, and edge cases.
Receiver responsibilities
The receiver should verify the signature, reject unknown event types, persist the event ID, and return a 2xx response only after the event is durably accepted. Slow work should move to a queue or background job.
Duplicate events are normal. Senders usually retry with at-least-once delivery, so the receiver must not assume one request equals one business effect.
Webhooks versus polling
| Approach | Strength | Cost |
|---|---|---|
| Webhook | Low latency, less wasted traffic | Receiver must expose and secure an endpoint |
| Polling | Simple receiver, works behind private networks | Higher latency and repeated empty requests |
Many integrations use both. Webhooks notify the receiver about changes, and polling or reconciliation catches missed events.
Reliability
Production webhooks need retries, signature verification, replay protection, idempotent processing, and observability. See webhook reliability patterns for the deeper implementation checklist.