methodEngineering & architecture

Webhook

A mechanism that sends an HTTP request to a registered receiver when an event occurs, avoiding repeated polling for changes.

Download Markdown (.md)

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]

Event delivery from a provider to a receiver-controlled endpoint A signed notification is acknowledged quickly, processed safely, and reconciled later
ProviderReceiver
  1. 01Receiver ProviderRegister endpointHTTPS URL and selected event types
  2. 02Provider ReceiverSigned eventIdentifier, timestamp, type, and payload
  3. 03Receiver ProviderPrompt acknowledgementVerify and durably record before slow work
  4. 04Provider ReceiverBounded retryRepeat after failed or missing acknowledgement
  5. 05Receiver ProviderReconciliation requestRecover authoritative state and expired deliveries

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

  1. The receiver registers an HTTPS URL and selects the event types it needs.
  2. The provider creates an event record and sends a signed request containing an identifier and payload.
  3. The receiver verifies the signature, timestamp, event type, and expected destination before trusting the content.
  4. The receiver records the event durably, returns a prompt success response, and processes work asynchronously when appropriate.
  5. The provider retries failed deliveries with limits, while the receiver deduplicates and monitors outcomes.
  6. The integration periodically reconciles critical state to recover from missing or expired deliveries.

05A practical example

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

  1. About WebhooksGitHub Docs · Official technical documentationAbout Webhooks
  2. Receive Stripe Events in Your Webhook EndpointStripe Docs · Official technical documentationReceive Stripe Events in Your Webhook Endpoint
View saved topics

Start typing to search titles, definitions, categories, and frameworks.