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
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 OKwithin 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.
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.