Webhook
A mechanism that sends an HTTP request to a registered receiver when an event occurs, avoiding repeated polling for changes.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/webhook/
01What it means
A webhook is an event notification delivered by one system to a receiver-controlled HTTP endpoint. The provider sends a payload when a subscribed event occurs, and the receiver acknowledges delivery before processing immediately or asynchronously. Webhooks are sometimes called HTTP callbacks.[1][2]
Webhook delivery is commonly at least once, may be delayed or out of order, and eventually stops retrying; receivers must deduplicate and reconcile critical state.
02Why it matters
Webhooks let integrations react quickly without continuously polling a provider. They can reduce needless requests and enable workflows such as payment updates, repository automation, and notifications, but they introduce security, duplicate-delivery, ordering, and recovery concerns.
03When to use it
Use webhooks when a provider can notify a known receiver about discrete events and near-real-time delivery matters. Polling may be safer when the receiver cannot expose an endpoint, notifications are not supported reliably, or periodic reconciliation is sufficient; streams may fit high-volume continuous events better.
04How it works
- The receiver registers an HTTPS URL and selects the event types it needs.
- The provider creates an event record and sends a signed request containing an identifier and payload.
- The receiver verifies the signature, timestamp, event type, and expected destination before trusting the content.
- The receiver records the event durably, returns a prompt success response, and processes work asynchronously when appropriate.
- The provider retries failed deliveries with limits, while the receiver deduplicates and monitors outcomes.
- The integration periodically reconciles critical state to recover from missing or expired deliveries.
05A practical example
A payment provider posts a payment.succeeded event to a subscription service. The receiver verifies the signature, stores the event ID, responds quickly, and queues entitlement activation. A repeated delivery is acknowledged but does not activate access twice.
06Where it breaks
Delivery is commonly at least once rather than exactly once, events may arrive late or out of order, and provider retry windows eventually end. Receivers need a public, secure, available endpoint and often still require reconciliation against the provider's authoritative state.
Common mistakes
- Trusting a payload without verifying its signature against the raw request body.
- Performing slow business work before acknowledging delivery and triggering unnecessary retries.
- Assuming events arrive exactly once, in order, or immediately.
- Using the notification payload as permanent truth without retrieval or reconciliation for critical state.
07Sources
- About WebhooksGitHub Docs · Official technical documentationAbout Webhooks
- Receive Stripe Events in Your Webhook EndpointStripe Docs · Official technical documentationReceive Stripe Events in Your Webhook Endpoint