# Webhook

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

- Type: method
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-23
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/webhook/>)

## What 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.

## Why 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.

## When 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.

## How 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.

## A 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.

## Where 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.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/webhook/#visualization-webhook>)

## Sources

1. [About Webhooks](<https://docs.github.com/en/webhooks/about-webhooks>) — GitHub Docs · Official technical documentation
2. [Receive Stripe Events in Your Webhook Endpoint](<https://docs.stripe.com/webhooks>) — Stripe Docs · Official technical documentation

## Related topics

- [Application Programming Interface \(API\)](<https://wiki.soroush.uk/topic/application-programming-interface/>)
- [Request and Response](<https://wiki.soroush.uk/topic/request-and-response/>)
- [Event-Driven Architecture](<https://wiki.soroush.uk/topic/event-driven-architecture/>)
