How to configure WhatsApp Business webhooks: technical guide 2026

Setting up WhatsApp Business webhooks in 2026 requires a public HTTPS callback URL, a verification token for the handshake with Meta, logic to process incoming JSON events (messages, status, templates, business_capability), and retrieval handling. For companies with an engineering team, this is the path to maximum flexibility; for everyone else, a platform like Aurora Inbox absorbs all the complexity and leaves application-specific webhooks to be handled when needed.

What is a WhatsApp Business webhook?

A webhook is a public HTTPS endpoint that Meta POSTs to every time an event occurs in your WhatsApp Business account: incoming message, status change (delivered, read), template approval, number quality change.

Without webhooks, there's no way to know what's happening in your API. They're the "push" way Meta notifies you.

Types of webhook events

Meta sends five categories of events:

Event	When it fires	Use case
messages	Customer sends message	Process the message and respond
statuses	Change of status of an outgoing message	Delivery tracking, read
template_status_update	Template approved/rejected/paused	Update your template UI
business_capability_update	Changes in tier, quality, or capabilities	Early warnings of problems
phone_number_quality_update	Changes in green/yellow/red quality	React before the ban

Configure webhook with Cloud API direct

Step 1: Have a public HTTPS callback URL

Your server must be:

• HTTPS with valid certificate (Meta rejects HTTP).
• Public (not localhost, not internal IP).
• Specific endpoint for webhook (e.g. https://tu-dominio.com/webhooks/whatsapp).

For local development, ngrok or similar tunnels work.

Step 2: Implement verification handshake

Meta sends initial GET request to verify your callback URL:

GET /webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=12345

Your server must:

1. Validate that hub.verify_token It matches the token you registered.
2. Return hub.challenge as a flat response.

Example in Node.js Express:

app.get('/webhooks/whatsapp', (req, res) => { if (req.query['hub.verify_token'] === process.env.WHATSAPP_VERIFY_TOKEN) { res.send(req.query['hub.challenge']); } else { res.status(403).send('Forbidden'); } });

Step 3: Process POST events

Once verified, Meta makes a POST request with the event:

{ "object": "whatsapp_business_account", "entry": [{ "id": "WHATSAPP_BUSINESS_ACCOUNT_ID", "changes": [{ "value": { "messaging_product": "whatsapp", "metadata": { ... }, "messages": [{ "from": "521234567890", "id": "wamid.xxxxx", "timestamp": "1716000000", "text": { "body": "Hi, how much does it cost?" }, "type": "text" }] }, "field": "messages" }] }] }

Your server must:

app.post('/webhooks/whatsapp', (req, res) => { const entry = req.body.entry[0].changes[0].value; if (entry.messages) { for (const msg of entry.messages) { processIncomingMessage(msg); } } if (entry.statuses) { for (const status of entry.statuses) { updateMessageStatus(status); } } res.sendStatus(200); // CRITICAL: respond 200 fast });

Step 4: Configure webhook in Meta App

In Meta App Dashboard:

1. WhatsApp → Configuration → Webhook.
2. Callback URL: https://tu-dominio.com/webhooks/whatsapp.
3. Verify Token: the string that your code compares.
4. Subscribe to fields: messages, message_template_status_update, etc.
5. Click Verify and SaveIf your handshake works, it's recorded.

Step 5: Validate security signature

Each POST is meta-signed with HMAC-SHA256. The signature is validated to prevent fraudulent requests.

const crypto = require('crypto');
function verifySignature(req) {
  const signature = req.headers['x-hub-signature-256'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WHATSAPP_APP_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');
  return signature === expected;
}

Error handling and retries

Meta retry the POST if your server:

• Returns a code other than 200.
• He/She does not respond in 5 seconds.

Good practices:

• Respond 200 immediately and processes the logic in the background with a queue.
• Idempotence. Each event has a wamid unique — if you receive duplicates, do not process twice.
• Logging full incoming payload for debugging.
• Alerts if the error rate increases.

Common errors in webhook configuration

• HTTP instead of HTTPS — Meta rejects.
• Invalid SSL certificate — Meta validates the certificate chain.
• Verify incorrect token — handshake fails.
• Process logic before returning 200 — timeout, Meta retreats.
• Do not validate signature — risk of fake requests.
• Do not handle duplicates — you process the same event twice.

The code-free alternative: Aurora Inbox

For 9 out of 10 SMEs, configuring raw webhooks is over-engineering. Aurora Inbox absorbs all the complexity:

• Webhook configured and maintained by Aurora Inbox.
• Processing incoming messages with AI agent ready.
• Status updates tracked on the dashboard.
• Managed templates in UI without touching API.
• Number quality monitored with early warnings.

If you need extensibility, Aurora Inbox exposes its own REST API where you can subscribe to application events that are more useful than Meta's raw events:

• conversation.created
• conversation.assigned
• ai_agent.escalated
• lead.qualified
• deal.stage_changed

Start your free trial and connect WhatsApp without touching raw webhooks.

Comparative table

Appearance	Webhook raw Cloud API	Aurora Inbox
Implementation time	1-3 weeks	10 minutes
Ongoing maintenance	5-15 hours/month	0
HTTPS / SSL	Your responsibility	Handled
Signature validation	Your responsibility	Handled
Retries / idempotence	Your responsibility	Handled
Payload processing	Your responsibility	Made
Application Webhooks	DIY	Available

Why Aurora Inbox

Aurora Inbox absorbs the complexity of WhatsApp Business webhooks and exposes higher-level application webhooks for your integrations. It combines a meta-level BSP, LLM agent, RAG, multichannel support, and a full REST API for extensibility.

Start your free trial and leaves the complexity of raw webhooks behind.

Frequently Asked Questions

Do I need a server to use WhatsApp webhooks?

For a direct Cloud API, yes. For a platform like Aurora Inbox, no—the platform handles the webhook.

How long does it take to set up a raw webhook?

1-3 weeks for a productive implementation with security and retries. Aurora Inbox: 10 minutes.

What events does Meta send via webhook?

messages, statuses, message_template_status_update, business_capability_update, phone_number_quality_update.

Do I need valid HTTPS for webhooks?

Yes. Meta rejects HTTP and invalid SSL certificates.

How do I avoid processing duplicate messages?

Each message has a wamid Unique. Saves processed IDs and rejects duplicates.

Can I have multiple webhooks for the same number?

Not directly in the Cloud API. The standard way is to have a single webhook that forwards to multiple internal destinations.