What is a webhook and how does it work: the definitive guide

A webhook is the simplest way for one system to tell another that something happened: instead of you asking every so often whether there's news, the service sends an HTTP request to your application the exact moment the event occurs. In this guide you'll understand how that works under the hood, when to use it (and when not to), and what a serious implementation needs.

The doorbell analogy

Imagine you ordered a package. There are two ways to know it has arrived: open the door every five minutes to check, or install a doorbell and let the courier ring when they get there. Querying an API repeatedly (polling) is opening the door every five minutes. A webhook is the doorbell: you provide an address and the other side takes care of notifying you.

Technically, a webhook is an HTTP request — almost always a POST with a JSON body — that a provider (Stripe, GitHub, Mercado Pago, Shopify…) sends to a URL you registered. That URL is an endpoint of your application, publicly reachable on the internet, ready to receive and process those notifications.

How a webhook works, step by step

1. You register a URL in the provider's dashboard or API — for example, https://your-app.com/webhooks/payments — and choose which events you want to receive (payment approved, order created, push to the repository…).
2. The event happens on the provider's side: a customer pays an invoice, a Pix transfer is confirmed, someone opens a pull request.
3. The provider builds a payload — a JSON document describing the event — and sends a POST to your URL, usually with identification headers and a cryptographic signature.
4. Your application responds with a 2xx status to acknowledge receipt. Any other response (or a slow one) is treated as a failure.
5. If delivery fails, the provider tries again — typically with increasing intervals (exponential backoff) over hours or days.

A real payload example

The structure varies by provider, but almost all of them follow the same envelope pattern: an event identifier, the type, the date and the data itself. A typical payment webhook looks like this:

{
  "id": "evt_1QxK2mLkdIwHu7ix",
  "type": "payment.approved",
  "created_at": "2026-07-25T14:32:07Z",
  "data": {
    "payment_id": "pay_9f8e7d6c",
    "amount": 14990,
    "currency": "BRL",
    "method": "pix",
    "customer_email": "customer@example.com"
  }
}

Note two details that show up in practically every serious provider: the event's id (which lets you detect duplicates) and the type (which lets you route processing). The headers that travel with this request — signature, delivery identifier, content-type — deserve a chapter of their own: we dissect everything in Anatomy of a webhook request.

Webhook vs. API: what's the difference?

Webhooks don't replace APIs — the two complement each other, and what changes is the direction of communication. With an API, you ask; with a webhook, they tell you.

A mature architecture usually uses both: webhooks to react fast, plus an API reconciliation routine (say, hourly) to cover any event lost along the way.

Where webhooks show up in everyday work

• Payments — Stripe, Mercado Pago, PagSeguro and friends notify you when a Pix transfer is confirmed, a card is declined or a subscription is canceled.
• Git and CI/CD — GitHub and GitLab fire webhooks on every push, pull request or release, and that's how deploy pipelines get started.
• Messaging — WhatsApp Business, Telegram and Slack deliver incoming messages via webhook.
• Digital products and e-commerce — Hotmart, Kiwify and Shopify notify sales, refunds and order status changes.
• Automation — Zapier, Make and n8n are, at their core, webhook routers between services.

What a serious implementation needs

Receiving a POST is easy; operating webhooks reliably in production is where the complexity lives. The essentials:

• Respond fast, process later. Acknowledge with 200 in milliseconds and push the heavy work onto a queue. Providers usually enforce timeouts of 5 to 30 seconds — blow past it and the delivery counts as a failure, followed by a retry.
• Be idempotent. Retries guarantee at-least-once delivery, which means the same event can arrive twice. Store the event's id and ignore duplicates.
• Verify the signature. Your endpoint is public; anyone can send a POST to it. The HMAC signature is what separates a legitimate event from a forged one — we explain the whole mechanism in Webhook security: HMAC signatures and best practices.
• Don't rely on ordering. A retry can make the "created" event arrive after the "updated" one. Use the event's timestamp (or query the API) as the source of truth for current state.
• Monitor and have replay. Silent webhook failures are notorious: everything looks fine until someone notices orders stopped landing in the system. Log every delivery and have a way to reprocess.

How to start experimenting

The best way to understand webhooks is to watch one arrive. The shortest path: point the provider's test webhook at an inspection endpoint — a temporary URL that captures and displays every incoming request, with headers and body nicely formatted (SafeHook does exactly that, and there are other options we compare later). Fire a test event and examine what arrives before writing a single line of code.

When you move on to building the real endpoint on your machine, you'll hit the classic "the provider can't reach my localhost" — the ways around it (tunnels, forwarding and CLIs) are covered in How to test webhooks on localhost. And before going to production, it's worth reviewing the 10 most common webhook implementation mistakes — nearly all of them are avoidable with simple decisions made early.

Summary

• A webhook is the provider calling you over HTTP when an event happens — the doorbell, not the door-watching vigil.
• The basic contract: POST with JSON, fast 2xx response, retries with backoff on failure.
• Production requires signature verification, idempotency, a processing queue and monitoring.
• Webhooks notify; the API confirms. Use both.