Webhooks Explained: What They Are and How They Work

Introduction

Webhooks are automated messages one system sends to another when something happens. Instead of asking a server for updates over and over, your app receives a callback as soon as an event occurs, usually over HTTP or HTTPS. That makes webhooks a fast, efficient way to move data between apps without constant polling.

They matter because they reduce delay and cut unnecessary requests. A payment can trigger an order update, a new form submission can start a workflow, or a shipping status change can notify your team instantly. This event-driven architecture lets systems react to events instead of waiting to be checked.

This guide covers what a webhook is in simple terms, how webhooks work step by step, how they compare with an API and a REST API, what a payload contains, and why security and reliability matter. You’ll also see how failures happen, how retries work, how to test a webhook endpoint, and how to troubleshoot common issues.

What is a webhook?

A webhook is an automated HTTP callback triggered by an event. One system, the source, sends data to another system, the destination, without waiting to be asked. This is why webhooks are often called event notifications: the source system notices something happened and immediately pushes a message onward.

Webhooks usually travel over HTTP or HTTPS and send a POST request with a JSON payload that includes the event type and related data. For example, Stripe can send a webhook when a payment succeeds, GitHub can notify your app when a new issue is opened, and Twilio can send delivery updates for messages. For a deeper breakdown, see what is a webhook and how webhooks work in simple terms.

Think of it like a doorbell or text alert: you do not keep checking the door or phone; you get notified when something happens. Webhooks are not a protocol like HTTP, but a pattern built on it. A webhook is sometimes compared with a callback or a reverse API, but the practical difference is simple: an API waits for a request, while a webhook sends the callback first.

How do webhooks work step by step?

Subscribe to events: Your app registers a webhook endpoint URL with the sender, such as Stripe, Shopify, GitHub, or EventBridge, and chooses which event types to receive.
An event happens: A payment succeeds, an order is created, a ticket is updated, or a message is delivered.
The provider sends a request: The source system builds a JSON payload and sends it to your webhook endpoint as an HTTP POST request.
Your endpoint verifies the request: Your app checks the signature, timestamp, and schema before trusting the payload.
Your app processes the event: The endpoint may enqueue work, update a database, notify Slack, or trigger a workflow in Salesforce or HubSpot.
Your endpoint returns a status code: If processing succeeds, return a fast 2xx response so the sender knows the event was received.
The sender retries if needed: If the request times out or returns a non-2xx response, retry logic may resend the event later.

This flow is explained in what is a webhook and how does it work and how webhooks work in simple terms.

Webhooks vs APIs

APIs are request-driven: your app asks for data or sends an update when it needs to, usually through a REST API. Webhooks are push-based: the server sends a callback over HTTP when an event happens. If you need to fetch a customer record from Stripe or update an order in Shopify, use an API; if you want instant notice that a payment succeeded or a GitHub issue was opened, use a webhook.

The tradeoff is latency versus control. Webhooks usually arrive faster because they avoid polling, while repeated API polling wastes requests and can miss timing windows. APIs are better for on-demand reads and writes; webhooks fit event-driven architecture when you want immediate notification, then an API call to retrieve full details. They do not replace each other — webhooks often trigger the workflow, and the API completes it.

Common webhook use cases

SaaS tools use webhooks to sync records and events across systems without polling. A new lead in HubSpot can trigger a Salesforce update, while a GitHub issue or pull request can notify Slack or start a CI workflow. The sending app posts an event type and payload to your webhook endpoint, so downstream tools act on the same event in real time.

Payments platforms like Stripe and PayPal rely on webhooks for critical billing events such as successful charges, failed payments, refunds, disputes, and subscription changes. In payments, webhooks are especially useful because the payment processor can notify your system immediately when a card is charged, a payout is completed, or a subscription renews, even if your app is not actively polling the API.

E-commerce platforms like Shopify use webhooks to keep storefronts, inventory, fulfillment, and customer records aligned when orders are created, canceled, paid, or refunded. For example, a Shopify order webhook can trigger warehouse picking, update stock counts, and send a confirmation email.

Webhook payloads, signatures, and security

A webhook payload usually includes the event type, a unique event ID, timestamps, and the object data related to the event. For example, a payment webhook might include the charge amount, currency, customer ID, and status. Some providers send a minimal payload and expect you to fetch the full resource with an API call.

Webhook endpoints are public-facing HTTP endpoints, so security depends on more than HTTPS alone. Use HMAC signature verification with a shared secret, compare the signature against the raw request body, and check the timestamp to reduce tampering and replay attacks. Add rate limiting and strict input validation, and validate the payload schema before processing it. See webhook security best practices.

A secure webhook setup should also log request IDs, signature failures, and processing errors so you can monitor abuse or misconfigurations. If a provider supports it, rotate secrets periodically and restrict which IPs or networks can reach the endpoint.

What happens when a webhook fails?

Failures are normal: a timeout, network error, schema mismatch, or non-2xx response should trigger provider retry logic, usually with exponential backoff. The sender may retry several times over a period of time, depending on the provider.

Design for idempotency by storing event IDs or unique keys so duplicate deliveries do not create duplicate charges, tickets, or database rows. If your handler receives the same event twice, it should safely return success without repeating the side effect.

For higher reliability, put incoming work on a queue, send poison events to a dead-letter queue, and use logging, monitoring, and replay tools to inspect and reprocess failures. If a provider offers replay, you can resend a missed event after fixing the underlying issue.

How do you test a webhook endpoint?

Start by sending a test POST request to your webhook endpoint with a known JSON payload that matches the provider’s schema. Verify that your app returns the expected 2xx response, checks the signature correctly, and handles duplicate deliveries without creating duplicate records.

Test both success and failure paths: invalid signatures, expired timestamps, malformed JSON, missing fields, and slow downstream dependencies. Confirm that logging and monitoring capture the request ID, event type, and processing result.

For setup and validation, follow the webhook testing checklist and compare tools in webhook testing tools.

How Hookdeck helps with webhooks

Hookdeck gives teams a central place to capture webhook traffic from sources like Stripe, GitHub, and Shopify, so you can inspect events before they hit your webhook endpoint. That makes it easier to see the full payload, spot malformed requests, and compare live traffic against your webhook testing checklist and webhook testing tools.

If a delivery fails, replay lets you resend the exact event after fixing a signature, parsing, or downstream issue. Combined with monitoring and alerting, that helps teams catch failures early instead of discovering them from customer reports. For teams handling many webhooks, Hookdeck also reduces logging, retry, and routing work, which lowers operational burden and makes production safer.

FAQ

Are webhooks push or pull?
Webhooks are push-based. The sending system pushes data to your endpoint as soon as an event happens, instead of waiting for your app to poll for updates.

Do webhooks use HTTP or HTTPS?
Yes. Webhooks use HTTP or, more commonly, HTTPS. They usually arrive as a POST request carrying event data in the request body.

What is the difference between a webhook and an API?
An API is request-driven: your app asks for data or sends an update when it needs to. A webhook is event-driven: the source system sends a callback to your webhook endpoint when something happens. In practice, webhooks often notify your app first, and an API call retrieves or updates the full resource.

What is included in a webhook payload?
A payload usually includes the event type, a unique event ID, a timestamp, and the object data related to the event. Depending on the provider, it may also include metadata such as account IDs, delivery IDs, or links to fetch more data through an API.

What happens if a webhook endpoint is down?
If your endpoint is unavailable or returns an error, the sender usually treats the delivery as failed and may try again later using retry logic. The exact retry schedule depends on the provider, so you should design your endpoint to respond quickly and handle duplicate deliveries safely.

Do webhooks retry automatically?
Often, yes. Many providers retry failed deliveries automatically using retry logic and exponential backoff. Some also stop after a fixed number of attempts, so you should check the provider’s documentation and build for duplicate events.

How do you verify a webhook signature?
Most providers sign the raw request body with HMAC and a shared secret. Your app recalculates the signature, compares it to the value in the request header, and checks the timestamp to make sure the request is recent. This is called signature verification.

What status code should a webhook endpoint return?
Return a fast 2xx response when the event was received and processed successfully. If the request is invalid, unauthorized, or cannot be processed, return the appropriate non-2xx status code so the sender knows the delivery failed.

What is idempotency in webhooks?
Idempotency means processing the same event more than once does not create duplicate side effects. You can implement it by storing the event ID, checking whether it has already been handled, and making your handler safe to replay.

Are webhooks secure?
They can be, if you use HTTPS, HMAC signatures, timestamp checks, schema validation, rate limiting, logging, and monitoring. Webhooks are not secure by default just because they are private to your app.

Can webhooks be used with APIs together?
Yes. This is a common pattern. A webhook notifies your app that something changed, and then your app uses an API to fetch the full record, update a system, or confirm the result.

What is a dead-letter queue in webhooks?
A dead-letter queue stores webhook events that could not be processed after retries. It helps teams inspect failures later without losing the original event.

How are webhooks used in payments and e-commerce?
In payments, providers like Stripe and PayPal use webhooks to report charges, refunds, disputes, and subscription changes. In e-commerce, platforms like Shopify use them to update orders, inventory, fulfillment, and customer notifications in real time.