What Is a Webhook?

A webhook is an HTTP request that one system sends to your application the moment something happens. Instead of your code repeatedly asking an API "is there anything new yet?", the other service pushes a small POST request to a URL you control as soon as the event occurs. You register an endpoint once, and updates arrive on their own.

How is a webhook different from polling an API?

Polling means your app calls an API on a schedule (every minute, say) to check for changes. Most of those calls return nothing, which wastes requests and adds lag between an event and your reaction. Webhooks invert that flow. The provider holds your endpoint URL and calls you when there is real news, so you find out close to instantly and you make zero idle requests.

The tradeoff is that webhooks need a publicly reachable URL and a receiver that is up when events fire. Polling, by contrast, works from anywhere and never exposes a listening endpoint. For high-volume, time-sensitive data (email delivery results, payment status, message events) webhooks are usually the better fit.

What does a webhook request look like?

A webhook is a normal HTTP request, almost always a POST, with a JSON body describing the event. A typical request has three parts worth knowing:

Method and path: POST to whatever URL you registered, for example https://api.yourapp.com/webhooks/email.
Headers: Content-Type: application/json, often a signature header (something like X-Signature) and an event type or delivery ID.
Body: a JSON payload with the event name and its data.

A delivery event might arrive as:

{
  "type": "email.delivered",
  "id": "evt_01H8...",
  "data": {
    "message_id": "msg_01H8...",
    "recipient": "person@example.org",
    "timestamp": "2026-06-29T10:24:00Z"
  }
}

What are webhooks used for?

Anywhere one system needs to tell another that state changed. Payment processors send a webhook when a charge succeeds or a card is disputed. CI systems fire one when a build finishes. Email platforms send them for deliveries, opens, clicks, bounces, and spam complaints. Bird pushes real-time email events to a webhook endpoint you configure, so your app can update a contact record or trigger a follow-up the instant a message is delivered or bounces. The mechanics behind those event types are covered in the email events guide.

How do you secure a webhook endpoint?

Your endpoint is a public URL, so treat every incoming request as untrusted until you prove otherwise.

Verify the signature. Reputable providers sign each payload with a shared secret. Recompute the HMAC over the raw request body and compare it to the header before you trust anything. Reject requests that fail.
Require HTTPS. Webhooks carry real data; do not accept them over plain HTTP.
Be idempotent. Networks retry, so the same event can arrive twice. Key your processing on the event ID and ignore duplicates you have already handled.
Respond fast, then process async. Acknowledge with a 2xx status quickly, push the payload onto a queue, and do the slow work afterward. If you do the slow work first, the sender may time out and retry.
Expect retries. Most providers retry failed deliveries with backoff. Returning a 5xx or timing out signals failure, so only return success once you have safely stored the event.

What does a minimal receiver look like?

Here is a small Node and Express endpoint that records the event and returns 200 straight away, leaving the real work for a background job:

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/email", (req, res) => {
  const event = req.body;

  // Acknowledge first so the sender does not retry.
  res.status(200).send("ok");

  // Then hand off the slow work.
  queue.add("process-email-event", event);
});

app.listen(3000);

In production you would verify the signature on the raw body before parsing it, and you would dedupe on event.id inside the queue worker.

Frequently asked questions

Are webhooks the same as an API?

They are related but point in opposite directions. A traditional API call is your app reaching out to a service. A webhook is the service reaching back to your app when something happens. Many platforms offer both, and you often use the API to send a request and a webhook to learn the result.

What should my endpoint return?

A 2xx status, quickly. That tells the sender the event was received. If you return an error or take too long, expect the provider to retry, which is why idempotent handling matters.

How do I test a webhook locally?

Use a tunneling tool (such as ngrok) to expose your local server on a public URL, register that URL with the provider, and trigger a test event. Log the raw body so you can confirm the signature and payload shape before writing real logic.

To wire delivery, open, and bounce events into your own app, see the email events guide and how Bird handles inbound email through an HTTP API. If you are tracking engagement specifically, tracking email opens builds directly on the open event a webhook delivers.