title: WhatsApp webhooks explained: a beginner's guide description: >- WhatsApp webhooks explained in plain English — what they are, how Meta uses them, what the payload contains, and how CodeWords removes the complexity. date: '2026-07-15' author: Rebecca Pearson authorAvatar: /blog/authors/rebeca-avatar.webp category: Resources cover: /blog/whatsapp-webhooks-explained/blog-thumbnail-blank.png readingTime: 5 tags:
- WhatsApp webhooks
- WhatsApp webhook setup
- WhatsApp Business API webhooks
- WhatsApp bot technical guide sourceUrl: 'https://www.codewords.ai/blog/whatsapp-webhooks-explained'
If you've ever tried to build a WhatsApp bot and hit a wall at the words "configure your webhook endpoint," this guide is for you. Webhooks are the mechanism that makes WhatsApp bots possible — but they're also one of the first places that people without a technical background get stuck.
This article explains what WhatsApp webhooks are, how they work, what's in the payload, and why CodeWords means you don't have to think about any of this if you don't want to.
TL;DR
- A webhook is a URL that receives data when something happens — in WhatsApp's case, when a message is sent to your number.
- Meta sends an HTTP POST to your endpoint within seconds of a customer sending a message. Your server must respond within a few seconds or Meta will retry.
- CodeWords sets up and manages all webhook infrastructure automatically — you describe your agent, Cody handles the rest.
What is a webhook?
A webhook is a URL — just like a web page URL — but instead of serving a page when a browser visits it, it receives data when a specific event happens somewhere else.
Think of it like a doorbell. When someone rings the bell (the event), a signal is sent to your phone (the webhook). Your phone receives that signal and you can decide what to do with it.
In the WhatsApp context: when a customer sends a message to your WhatsApp number, Meta's servers ring your doorbell. They send the message content, along with information about who sent it, to a URL you've registered with Meta. Your server receives that data and runs whatever logic you've built — looking up context, calling an AI model, sending a reply.
How WhatsApp uses webhooks
When you connect a WhatsApp Business number to a bot, you register a webhook URL with Meta. This is a URL hosted on your server that Meta knows to call whenever something happens on your WhatsApp account.
The events Meta can send to your webhook include:
- Message received: a customer sent you a text, image, audio, video, or document
- Message status update: a message you sent was delivered, or read
- Message reaction: a customer reacted to a message with an emoji
The most important event for bot builders is "message received." Every time this fires, your webhook gets a POST request containing the full message details, and your bot has a chance to respond.
What's in the webhook payload
A typical WhatsApp webhook payload (the data Meta sends to your URL) includes:
{
"object": "whatsapp_business_account",
"entry": [{
"changes": [{
"value": {
"messages": [{
"from": "447911123456",
"id": "wamid.unique_message_id",
"timestamp": "1720000000",
"text": { "body": "Hi, what are your opening hours?" },
"type": "text"
}],
"contacts": [{
"profile": { "name": "Sarah Jones" },
"wa_id": "447911123456"
}]
}
}]
}]
}
From this payload, your bot can extract the sender's phone number (from), their display name, the message content (body), the message type (text, image, audio), and a unique message ID.
If the message is an image or audio file, the payload contains a media ID instead of text content — you'd then call Meta's API separately to download the actual file.
Why your endpoint must respond within seconds
Here's where many first-time webhook builders run into problems. Meta expects your webhook endpoint to respond with an HTTP 200 status code within five seconds of sending the payload. If it doesn't, Meta assumes something went wrong and will retry — potentially multiple times.
If you're processing a message (calling an AI model, looking up a database, generating a reply), that can easily take three to ten seconds. If all of that processing happens before you return a 200 response, you'll miss Meta's window and trigger retries.
The solution is the async processing pattern.
The async processing pattern
The right way to handle WhatsApp webhooks is to split the work in two:
Step 1 — acknowledge immediately: as soon as the webhook request arrives, return a 200 OK response to Meta. This tells Meta "we got it, everything's fine." Do this within one second.
Step 2 — process in the background: after acknowledging, hand the message off to a background worker or queue. The worker does the actual work — retrieving memory, calling the AI model, fetching CRM data, composing the reply, sending it back via the WhatsApp API. This can take as long as it needs to.
This pattern prevents retries and prevents duplicate messages. It's a standard practice in webhook-based systems but it requires infrastructure that many non-developers don't have set up.
Webhook verification
Before Meta will start sending events to your webhook, it performs a verification step. It sends a GET request to your URL with a hub.verify_token parameter that you define when setting up the integration. Your server needs to recognise that token and respond with a specific value.
This is just Meta confirming that you own the URL you've registered. It happens once, at setup. But it's another step that requires your server to be correctly configured and publicly accessible on the internet — which rules out running a webhook on your local computer.
How CodeWords removes the complexity
If you're using CodeWords to build your WhatsApp agent, you never touch any of this.
CodeWords hosts the webhook infrastructure. When you describe your agent to Cody (the AI automation assistant) and connect your WhatsApp number, Cody registers and manages the webhook endpoint on CodeWords' infrastructure. The async processing pattern is handled automatically. Verification is done during the connection flow. Retries and delivery guarantees are managed at the platform level.
From your perspective, you describe what you want your agent to do, and messages start flowing. You don't register webhook URLs. You don't stand up a server. You don't write async processing code.
For developers who want to build on top of webhook infrastructure directly, tools like n8n and Make give you visibility into the full payload and let you write custom logic around it. But for the majority of businesses building WhatsApp agents, abstracting that complexity away is the right call.
If you want to understand the broader architecture of how WhatsApp bots process and remember conversations, read our guide on how to add AI memory to your WhatsApp chatbot. And if you're ready to build your first agent without dealing with any of this configuration yourself, start with how to build a WhatsApp AI agent in 2026.
Start building on CodeWords — webhook setup included, no configuration required.