WhatsApp Webhooks Guide: Receive Message Events in Real Time

Short answer: a webhook is a URL on your server that WhatsApp sends an instant HTTP request to whenever a new event happens, like an inbound message from a customer or a status change on a message you sent. Instead of your system asking WhatsApp "anything new?" every second, WhatsApp knocks on your door the moment the event occurs, so you receive data in real time with far fewer resources.

In this guide we walk through it step by step: what a webhook is in plain terms, how it differs from polling, the WhatsApp event types you receive, how to build an endpoint to receive them, how to secure it with signature verification, and the most practical use cases.

What a webhook is in plain terms

Imagine you ordered a delivery. Instead of calling the restaurant every five minutes to ask where your order is, the restaurant texts you the moment it leaves the kitchen and again when it arrives at your door. That is exactly what a webhook does in software.

Technically, a webhook is an endpoint (a URL) that you set up on your server and register with the provider. Whenever an event tied to your account happens, the provider sends an HTTP POST request to that URL, with the body in JSON format containing the event details. Your job is to receive that request, read the data, and respond quickly with 200 OK to confirm you received it.

The core idea is that the connection flows from WhatsApp toward you, not the other way around, so your system stays in a listening state ready to receive at any moment.

The difference between webhook and polling

There are two ways to learn that a new event happened: polling and webhooks. With polling, your system asks WhatsApp at short intervals "any new messages?", even when nothing is new, so you burn requests and resources for no reason and add latency equal to the gap between each check.

With a webhook you never ask, because WhatsApp pushes the data the moment the event happens. The result is near-instant response under one second with far fewer requests, since there are no wasted checks.

The takeaway is that webhooks are the right choice for any serious messaging app, because how fast you reply to a customer makes a real difference in their experience.

WhatsApp event types you receive

WhatsApp sends you several event types, and each one has its purpose. The key ones are:

• Inbound messages (message): the most important event of all, fired the moment a customer sends you text, an image, a file, or a reaction, carrying the message content, the sender number, and the timestamp.
• Message status: tells you a message you sent became sent, delivered, read, or failed.
• Template and button replies: fired when a customer taps a button, picks from an interactive list, or replies to a template message.
• Session and connection events: like a change in the number's link status or a dropped session, useful for monitoring account health.

The table below maps each event to when it fires and its practical use:

Event type | When it fires | Use

Inbound message: when a customer sends a message, used to trigger a WhatsApp bot or open a support ticket. Delivery status: when your sent message changes state, used to update your campaign dashboard and track reach. Interactive reply: when a customer taps a button or list, used to route the conversation by their choice. Session status: when a number links or disconnects, used to alert your team that the account dropped.

How to build an endpoint to receive

Setting up a receiving point is simpler than you think. You need a public URL (HTTPS required) that accepts POST requests. The workflow:

1. Create a route in your app like /webhooks/whatsapp that accepts POST.
2. Read the request body as JSON and parse it.
3. Verify the signature before trusting the data (covered shortly).
4. Process the event quickly, or push it to a queue to handle in the background.
5. Respond immediately with 200 OK, because any delay or error makes WhatsApp retry.

The golden rule: do not run heavy logic inside the request itself. Receive, store, and respond fast, and keep the real processing in the background. This prevents timeouts and protects you from duplicate deliveries.

A simplified inbound message payload:

{
  "event": "message.received",
  "data": {
    "from": "966500000000",
    "type": "text",
    "text": "Hi, is my order ready?",
    "timestamp": 1718500000
  }
}

Webhook security and signature verification

A webhook URL is public, so anyone who knows it can send it fake data. That is why signature verification is not optional, it is essential. The idea is that WhatsLoop computes an HMAC signature of the message using a secret key only you know, and sends it in a header with every request, so you recompute the same signature over the raw body and compare.

The verification steps:

1. Take the raw request body as it arrived, before any modification.
2. Compute HMAC-SHA256 of the body using your secret key.
3. Compare the result with the signature value in the header using a constant-time comparison.
4. If they do not match, reject the request immediately with 401 and process nothing.

Beyond the signature, apply these habits: always use HTTPS, store the secret key in environment variables not in code, and handle every event idempotently, because WhatsApp may resend the same event more than once when a fast response does not arrive.

Practical use cases

Webhooks are the backbone of any serious WhatsApp automation. The main things you build on top of them:

• Instant auto-reply: the moment a message arrives, the bot fires and replies within a second, so the customer never waits.
• Conversation routing: based on a keyword or a button the customer taps, route the conversation to the right department or agent.
• Campaign tracking: receive delivery and read statuses for each message, and build an accurate dashboard for reach and open rates.
• Integration with your systems: every inbound message creates a support ticket or updates the customer record in your CRM automatically.
• Operational alerts: if your number's session drops, you get an instant alert before customers are affected.

All these scenarios start from the same point: an endpoint that receives the event in real time. With the WhatsLoop WhatsApp API, you set up your webhook URL and register it in minutes, then start receiving every event on your account with a verified signature and a clear JSON format, so you build your automation on top with confidence. Try connecting today and let your system hear your customers first.