Webhooks

What Webhooks Actually Means

A webhook is a mechanism where a server sends an HTTP POST request to a pre-configured URL when a specific event occurs. Instead of the client repeatedly polling for updates (pull), the server pushes notifications to the client (push). Webhooks are the push-based alternative to polling.

When to Use It (and When Not To)

Webhooks enable event-driven integrations without continuous polling. They are used by virtually every SaaS platform (Stripe, GitHub, Slack, Twilio) to notify your application of events in real-time.

The Architecture

You register a webhook URL with the service (e.g., tell Stripe to POST to https://myapp.com/webhooks/stripe). When an event occurs (payment succeeded, payment failed), Stripe sends an HTTP POST to your URL with the event data as JSON. Your server processes the event (update order status, send email) and returns 200 OK. If your server is down or returns an error, Stripe retries.

Key Principles

• Push model: The server notifies the client when an event occurs, rather than the client asking repeatedly.
• HTTP POST: Webhook payloads are delivered as HTTP POST requests to a URL you configure.
• Idempotency: Webhooks may be delivered multiple times. Your handler must be idempotent — processing the same event twice should not cause problems.
• Verification: Sign webhook payloads with a secret (HMAC) so the receiver can verify the sender is authentic.
• Retry logic: If your endpoint returns a non-2xx status, the sender retries with exponential backoff.

Who Does This Well

Stripe sends webhooks for payment events (succeeded, failed, refunded). This is how merchants update order status in real-time.

GitHub sends webhooks for repository events (push, pull request, issue). This triggers CI/CD pipelines.

Slack receives incoming webhooks to post messages to channels from external services.

The Hard Parts Nobody Talks About

1. Not verifying webhook signatures — exposes you to spoofed events
2. Processing webhooks synchronously — if your handler is slow, the sender may time out and retry
3. Not making handlers idempotent — duplicate deliveries cause duplicate processing

The Tradeoffs

• Push (webhook) vs Pull (polling): Webhooks are more efficient but harder to debug. Polling is simpler but wastes resources.
• Reliability: You depend on the sender's retry logic. If they stop retrying and you missed the event, data is lost.
• Security: Without signature verification, anyone can send fake webhooks to your endpoint.

Interview Angles

1. What is a webhook and how does it differ from polling?
2. How do you ensure webhook delivery reliability?
3. How do you secure webhooks?
4. What happens if the webhook receiver is down?

Keep Learning

• What is an API
• Pub/Sub
• idempotency
• push-vs-pull-architecture

Original DosiBridge notes for Webhooks

This section is written specifically for this page, not copied from a general system-design checklist. The useful way to study Webhooks is to connect the concept to an integration boundary where bad contracts become customer-facing outages. That framing changes the design discussion from definitions to operating choices.

What makes this topic distinct

• Contract Evolution: For Webhooks, decide the contract evolution before choosing tools; otherwise the design looks clean but fails when webhooks changes.
• Idempotency: For Webhooks, decide the idempotency before choosing tools; otherwise the design looks clean but fails when webhooks changes.
• Pagination: For Webhooks, decide the pagination before choosing tools; otherwise the design looks clean but fails when webhooks changes.
• Error Shape: For Webhooks, decide the error shape before choosing tools; otherwise the design looks clean but fails when webhooks changes.
• Consumer Compatibility: For Webhooks, decide the consumer compatibility before choosing tools; otherwise the design looks clean but fails when webhooks changes.

Production review question

If a team adopts Webhooks, what observable signal proves it helped instead of only making the architecture diagram more fashionable?

Practical metric to track

Track webhooks health as a named dashboard or review item: combine one user-facing metric, one saturation metric, and one correctness metric. For Webhooks, this keeps the discussion grounded in behavior that can be measured after deployment instead of generic advice that sounds good in an interview but never gets verified.