Definition

What Is a Webhook? How Webhooks Work, With Examples

Get notified the moment something happens instead of asking over and over. Here's how webhooks work, how to secure one, and the mistakes that cause duplicate events.

Shradha R Shradha R

Webhook vs API polling

Webhook

API polling

Who starts the request

The provider, when an event happens

Your app, on a timer

Latency

Near real time (usually seconds)

Up to one polling interval

Wasted requests

None; one request per event

Most requests return nothing new

What you need to run

A public HTTPS endpoint

A scheduler and an API key

Missed events

Possible during downtime; providers retry

Unlikely if you track a cursor

Security work

Verify every incoming request

Protect your outgoing API key

Best for

Reacting to events as they happen

Backfills, reports, providers without webhooks

What is a webhook?

A webhook lets one system tell another that something happened, the moment it happens. You give a provider a URL. When an event occurs (a payment clears, a message is sent, a build finishes), the provider sends an HTTP POST to that URL with the details in a JSON body.

Without webhooks you'd poll: ask the provider's API every few seconds whether anything changed, and get "no" most of the time. Webhooks flip that around. Your server stays quiet until there's something to act on, so you get the update sooner and make far fewer requests.

People also call them HTTP callbacks or reverse APIs. The webhook endpoint is the URL on your side that receives the POST.

How webhooks work

1. Register an endpoint

You create a public HTTPS route on your server, such as https://api.example.com/webhooks/chat, and register it with the provider. Most providers let you choose which events to subscribe to, so you only receive what you need.

2. The provider sends the event

When a subscribed event fires, the provider sends a POST request with a JSON payload. A typical payload includes an event type, an event ID, a timestamp and the object that changed.

3. You verify and acknowledge

Your endpoint checks that the request really came from the provider, then replies with a 2xx status. Providers use one of two methods to prove who sent it: a shared secret in an Authorization header (Basic Auth or a bearer token), or an HMAC signature of the body that you recompute and compare.

4. You process it, ideally later

Do the real work (update a database, send an email, call another API) in a background job. If your endpoint takes too long to answer, the provider treats the delivery as failed and sends it again.

Webhook example: a secure receiver in Node.js

This Express receiver checks a Basic Auth header in constant time, acknowledges straight away, ignores duplicates and hands the event to a queue.

const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.json());

const creds = `${process.env.HOOK_USER}:${process.env.HOOK_PASS}`;
const expected = Buffer.from('Basic ' + Buffer.from(creds).toString('base64'));
const seen = new Set(); // use Redis or a database table in production

app.post('/webhooks/chat', (req, res) => {
  const got = Buffer.from(req.get('authorization') || '');
  if (got.length !== expected.length || !crypto.timingSafeEqual(got, expected)) {
    return res.sendStatus(401);
  }
  res.sendStatus(200);                 // acknowledge fast
  const eventId = req.body.id;         // check your provider's field name
  if (seen.has(eventId)) return;       // retried delivery, already handled
  seen.add(eventId);
  setImmediate(() => console.log('process', req.body)); // swap for a job queue
});

app.listen(3000);

Rule of thumb: verify, acknowledge, then process. Anything slow belongs in a queue, not in the request that the provider is waiting on.

Common webhook use cases

  • Chat and messaging: run moderation, update a CRM or alert an agent when a message is sent, edited or flagged.

  • Payments: mark an order paid when the payment provider confirms the charge.

  • CI/CD: start a deploy when code is pushed to a branch.

  • Calls: save a recording link or bill usage when a call ends.

  • Notifications: send an email or SMS to a user who missed a message while offline.

Limits and pitfalls

  • Deliveries can be repeated. If your 200 response is lost or slow, the provider retries. Store the event ID and skip anything you've already processed.

  • Order isn't guaranteed. A "message edited" event can arrive before "message sent" after a retry. Use timestamps or version numbers, not arrival order.

  • Slow endpoints fail. Answer within a couple of seconds and queue the work. Long database writes inside the request are the most common cause of duplicate deliveries.

  • Unverified endpoints are an open door. Anyone who finds the URL can POST to it. Always check credentials or the signature, and use HTTPS.

  • Downtime means gaps. Retries stop eventually. Keep a way to backfill from the provider's REST API after an outage.

  • Local testing needs a tunnel. The provider can't reach localhost, so use a tunnelling tool or a request inspector while developing.

Webhooks in CometChat

If you're adding chat or calling to your app, webhooks are how your backend keeps up with what happens in conversations without polling.

Get chat, call and moderation events on your server

CometChat sends an HTTP POST with a JSON payload to your HTTPS endpoint when events happen: messages sent, edited, deleted, delivered or read, reactions, group changes, user status, calls and meetings starting and ending, recordings, and moderation decisions. Endpoints are secured with Basic Authentication. CometChat asks you to return 200 OK within 2 seconds and to use event IDs to ignore retried deliveries, which is exactly the pattern in the example above. You can set webhooks up in the dashboard or through the Management API.

Read the webhooks docs · Start building free

Frequently asked questions

What is the difference between a webhook and an API?

With an API, your app asks for data when it wants it. With a webhook, the provider sends data to your app when an event happens. Most providers offer both: webhooks for real-time events and an API for reading and backfilling.

What is a webhook endpoint?

It's the URL on your server that receives webhook requests, for example /webhooks/chat. It must be publicly reachable over HTTPS, accept POST requests and return a 2xx status quickly.

Are webhooks secure?

They are if you verify every request. Use HTTPS, check the provider's Basic Auth credentials or HMAC signature, and reject anything that doesn't match. Never trust a payload just because it reached your URL.

What happens if my webhook endpoint is down?

Most providers retry failed deliveries for a period, then give up. Make your handler idempotent so retries are harmless, and backfill from the provider's API after a long outage.

Is a webhook push or pull?

Push. The provider pushes the event to you over HTTP. Polling is pull.

Related terms