What Are Webhooks?

The core idea

A webhook is an HTTP request that one system sends to another the moment an event of interest occurs. Rather than your application repeatedly asking a provider has anything changed?, the provider tells you the instant it has. You register a URL — your endpoint — and the provider makes a POST request to it whenever a relevant event fires. There is no schedule and no waiting; the notification rides on the event itself.

People often call webhooks reverse APIs, and the nickname is apt. With a normal API your code is the client, initiating each call and waiting for a reply. With a webhook the roles flip: the provider becomes the client and your server becomes the listener. The payload that arrives describes what happened, usually as a JSON document, and your job is to receive it and react.

Anatomy of a delivery

A typical delivery is a single HTTPS POST. The body carries the event data, while headers carry metadata such as an event identifier, a timestamp, and a signature you can use for verification. Your endpoint reads the body, does whatever work the event requires, and returns a status code to tell the provider how it went.

POST /hooks/incoming HTTP/1.1
Content-Type: application/json

{
  "id": "evt_123",
  "type": "resource.updated",
  "created_at": "2026-06-29T04:00:00Z",
  "data": { "...": "..." }
}

A 2xx response tells the provider you accepted the event and it can move on. Anything else is usually treated as a failure that is worth retrying, so the status code you return genuinely matters.

Provider and consumer

It helps to name the two sides clearly. The provider generates events and sends deliveries; the consumer — that is you — receives and processes them. The provider owns the catalogue of event types and the shape of each payload. The consumer owns the endpoint, the verification, and the business logic that runs in response to each event.

This separation is exactly what makes webhooks powerful. The provider does not need to know anything about your internal systems — only the URL to call. You, in turn, do not need to poll on a timer or hold open long-lived connections waiting for something to happen. Each side stays loosely coupled to the other, free to change independently as long as the event contract between them holds steady.

When webhooks fit

Webhooks shine when events are sparse and unpredictable, when you want changes reflected quickly, and when constant polling would simply waste effort. They suit notifications, status changes, and lifecycle events — anything where being told promptly is worth more than asking on a schedule. For an overview of how Merion exposes its API, see the API documentation, then continue with webhooks vs polling to compare the alternatives side by side.

They are less suited to bulk data transfer, to cases where you need a strictly guaranteed ordered stream of records, or to situations where you cannot expose a public endpoint at all. In those circumstances a polling or batch approach may serve you better, and recognising the difference early saves a lot of rework later.