How Webhooks Work: Simple Guide with Examples

Introduction: what readers will learn

Webhooks are event-driven HTTP callbacks that send data the moment something happens, so systems can react without waiting for a manual check. If you’ve ever wanted one app to notify another instantly instead of repeatedly asking for updates, that’s the problem webhooks solve.

They reduce polling, speed up automation, and let different tools communicate across an API-driven workflow with less wasted effort. A webhook is a lot like a doorbell: instead of checking the door every few seconds, you wait for the bell to ring when someone arrives.

This guide explains what a webhook is in simple terms, how webhooks work step by step, what a webhook endpoint is, what data is sent in a webhook payload, and how to secure delivery with HTTPS, HMAC signatures, shared secrets, and timestamp validation. It also covers retry logic, idempotency, deduplication, status codes, and what to do when delivery fails.

You’ll also see how webhooks fit into event-driven architecture, why they often beat polling for real-time updates, and how webhooks and APIs work together. For a broader starting point, see what a webhook is, webhooks in simple terms, and webhook basics. For more resources, visit WebhookGuide or browse the WebhookGuide blog.

What is a webhook?

A webhook is an event-driven HTTP callback: one app sends data to another app when something happens, instead of waiting for the other app to ask for it. That’s the core idea behind how webhooks work: Stripe can notify your server when a payment succeeds, or GitHub can send an event when code is pushed.

A REST API request works the other way around. Your client initiates the call, chooses when to send it, and asks the API for data. With a webhook, the sender pushes a webhook payload to your webhook endpoint, usually as an HTTP POST to a callback URL.

People also call webhooks reverse APIs or event notifications, but those terms are imperfect because webhooks usually complement an API rather than replace it. You often use the API to verify, fetch, or enrich the event data after the webhook arrives.

How do webhooks work step by step?

1. An event happens in the provider system, such as a Stripe payment succeeding, a GitHub push, or a GitLab merge request being opened.
2. The provider creates a JSON webhook payload and sends it over HTTPS as an HTTP POST request to your configured webhook endpoint.
3. The request usually includes headers such as an event ID, a timestamp, and an HMAC signature generated with a shared secret.
4. Your server receives the request, validates the signature, checks timestamp validation to reduce replay risk, and confirms the payload is from the expected source.
5. Your handler returns a fast 2xx response if the event was accepted. If you need to do heavier work, hand it off to a background job or queue.
6. If the provider gets a timeout or a non-2xx status code, it may trigger delivery retries according to its retry logic.
7. If repeated attempts still fail, some systems move the event to a dead-letter queue or a failed-delivery view for later inspection.

That flow is what makes webhooks feel real time: the sender reacts to the event immediately, and your system receives the notification as soon as the provider processes it.

Webhook payloads, endpoints, and security

An event is what happened; the webhook payload is the data sent about it. A Stripe payment_intent.succeeded event, for example, usually includes the event type, object ID, timestamps, and metadata in JSON, but may omit full object details so you need a follow-up API call to fetch the latest record. That partial design keeps payloads smaller and avoids stale data.

A webhook endpoint is the stable, publicly reachable HTTPS URL that receives the POST request, such as /webhooks/stripe or /webhooks/github. Keep the route clear and consistent so your server can route requests reliably.

To secure a webhook endpoint, use HTTPS, verify the HMAC signature with the shared secret, validate the timestamp, and reject requests that fail signature checks. IP allowlisting can add another filter, but it should not replace signature verification. For extra protection, log the request ID, store the raw payload, and monitor failed attempts so suspicious traffic is visible.

Webhooks vs APIs: when to use each

Webhooks push data automatically when an event happens; an API usually waits for your client to request data, often through polling or a direct REST API call. That makes webhooks better for immediate notifications, while APIs give you on-demand retrieval and tighter control over what you fetch.

Webhooks	APIs
Push-based	Pull-based
Real-time event delivery	On-demand data access
Best for alerts and automation	Best for fetching, confirming, or updating data
Less polling overhead	More control over request timing

Use webhooks for event-driven architecture: Stripe payment alerts, GitHub push notifications, GitLab CI/CD triggers, or Slack-style automation. Use APIs after the webhook arrives to verify the event, fetch the full record, or update related resources. That’s why webhooks and APIs are complementary, not competing technologies. For a refresher, see what a webhook is and webhooks in simple terms.

Real-world webhook examples

A Stripe payment_intent.succeeded webhook can trigger order fulfillment, send a receipt, and update your CRM; a charge.refunded event can reverse access or notify support. PayPal uses similar payment notifications for renewals and refunds, so your backend reacts the moment money moves. The payload usually includes the event type, transaction ID, amount, and customer details, which lets you match the event to an order and automate the next step.

A form tool like Typeform or Webflow can send a lead webhook to HubSpot, Salesforce, or another CRM the instant someone submits a form. That payload typically carries the contact fields, form name, and submission time, so sales can respond faster or route the lead through Zapier or Make without manual entry.

For engineering, GitHub and GitLab webhooks can fire on a push or pull request and start CI/CD builds, run tests, deploy to staging, or post a Slack alert. That is a practical example of event-driven automation: one event triggers one workflow, immediately.

Common webhook problems, testing, and best practices

Webhooks are simple in concept, but production systems need careful handling. Delivery can fail if your endpoint times out, returns a non-2xx response, or hits a network error, so providers like Stripe and GitHub use retry logic and delivery retries. To avoid duplicate processing, build idempotency around event IDs and deduplication: store each event ID once, and ignore repeats.

Common webhook problems include misconfigured callback URLs, expired or incorrect shared secrets, signature mismatches, clock drift that breaks timestamp validation, blocked HTTPS traffic, and handlers that take too long to respond. If a webhook is not firing, check whether the provider has the correct webhook endpoint, whether the event type is enabled, whether your server is reachable, and whether your logs show incoming requests.

Debugging depends on observability: use logging, monitoring, delivery dashboards, correlation IDs, and inspect status codes for each attempt. A good webhook testing checklist includes signature verification, retry tests, malformed payloads, and confirming the endpoint returns the right 2xx response. Follow webhook best practices: use HTTPS, respond quickly, store raw payloads, version events, monitor failures, and use a dead-letter queue or replay strategy when messages keep failing.

To test a webhook, use a staging endpoint, a tool such as Stripe CLI or GitHub’s delivery test features, and a checklist that confirms the payload shape, signature validation, retry behavior, and duplicate handling. You can also replay a known event to verify that your handler is idempotent and that your logs capture the full request.

Conclusion: how webhooks work in one sentence

A webhook is an event-driven HTTP POST request that lets one system instantly notify another when something happens. That’s the simplest way to understand webhooks: an event occurs, the provider sends a payload, and your endpoint reacts without polling.

The details still matter. Secure webhooks with signatures or shared secrets, expect retries when delivery fails, and design your handler to process duplicate events safely. In real systems, webhooks and APIs usually work together: the webhook tells you something changed, and the API helps you fetch or update the full record.

If you’re building next, start with a webhook testing checklist to verify your endpoint, then review webhook best practices for security, reliability, and idempotency. For deeper implementation guidance, WebhookGuide is a useful reference.

Use webhooks when you need immediate, automated updates as part of an event-driven architecture.