Skip to content
TXTPro

Webhook documentation

WhatsApp Business API Webhook Integration

A WhatsApp Business API webhook is the callback URL to which Meta’s WhatsApp Business Platform sends incoming customer messages and status updates (sent, delivered, read and failed) for messages from your business number.

Updated

How Meta’s webhook architecture works

On the WhatsApp Business Platform, webhooks are configured on a Meta app. The app is subscribed to a WhatsApp Business Account (WABA), and to the webhook fields it needs. When something happens on a business phone number in that account, Meta sends an HTTPS POST to the app’s callback URL.

Who owns that callback URL depends on your setup. If you manage your own Meta app, Meta calls your server directly. If your WhatsApp access is provided through TXTPro, events may be received by the platform and then forwarded to you. Which model applies is confirmed during onboarding.

Incoming customer messages

When a customer writes to your business number, the webhook contains the message with a type such as text, image, document, audio, location, contacts or an interactive reply, plus the sender’s WhatsApp ID and a timestamp. Media arrives as a media ID that must be downloaded separately through the API.

An incoming message also opens or refreshes the customer service window during which you can reply freely; outside it, Meta requires an approved template. See WhatsApp Business API for how templates work.

Message status updates

WhatsApp message statuses reported by Meta
StatusMeaning
sentMeta accepted the message and sent it towards the recipient.
deliveredThe message reached the recipient’s device.
readThe recipient opened the message.
failedThe message could not be delivered; the update includes error details.

Status updates reference the WhatsApp message ID (beginning wamid.) returned when you sent the message. Store it to correlate updates.

Delivered and read receipts

Delivered and read updates arrive as separate events. Customers can turn off read receipts in their privacy settings, in which case you may see delivered but never read. Report read rate as a minimum, and do not resend a message just because no read event arrived.

Failed message events

A failed status includes an error object with a code and title. Common causes include messaging a customer outside the service window without a template, using a template that is paused or not approved, or a recipient who cannot receive the message. Store the error code and look it up in Meta’s error reference rather than guessing; codes and meanings are maintained by Meta and change over time.

Interactive replies

When a customer taps a reply button or chooses an item from a list message, the incoming message carries the ID you assigned to that button or row, along with its title. Quick-reply buttons on templates arrive as button replies with their payload. Use the IDs, not the visible titles, to decide what happens next, because titles can be translated or edited.

Webhook verification

When a callback URL is registered with Meta, Meta sends a GET request with hub.mode=subscribe, hub.verify_token and hub.challenge. Your endpoint must confirm the verify token matches the value you configured and respond with the challenge value. Meta requires the callback URL to use HTTPS with a valid certificate.

Pattern for Meta’s documented verification handshake and signature check (Node.js / Express)
// WhatsApp Cloud API (Meta) endpoint verification and payload signature check.
// Meta sends a GET request when you register the callback URL, and signs each
// POST with X-Hub-Signature-256 using your Meta app secret.
import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.get('/webhooks/whatsapp', (req, res) => {
  const ok = req.query['hub.mode'] === 'subscribe' && req.query['hub.verify_token'] === process.env.META_VERIFY_TOKEN;
  return ok ? res.status(200).send(req.query['hub.challenge']) : res.sendStatus(403);
});

app.post('/webhooks/whatsapp', express.raw({ type: 'application/json', limit: '256kb' }), (req, res) => {
  const header = req.get('X-Hub-Signature-256') ?? '';
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.META_APP_SECRET).update(req.body).digest('hex');
  const valid = header.length === expected.length && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
  if (!valid) return res.sendStatus(401);
  // Queue JSON.parse(req.body) for asynchronous processing, then acknowledge.
  return res.sendStatus(200);
});

Security considerations

  • The verify token only protects the registration handshake. Authenticate every POST by checking the X-Hub-Signature-256 header, an HMAC-SHA256 of the raw body computed with your Meta app secret.
  • Compute the signature over the raw bytes before parsing JSON, and compare it in constant time.
  • Keep the app secret and verify token in a secrets manager; never in client-side code.
  • Incoming messages contain personal data and free text. Mask phone numbers in logs and never log message bodies.

These are Meta’s mechanisms for direct integrations. If events reach you through TXTPro, the authentication used for forwarded events is confirmed during onboarding. See the webhook security guide.

Event subscriptions

In Meta’s model, incoming messages and message status updates are delivered through the messages webhook field. Meta offers other fields for account-level changes, such as template status updates. Subscriptions only take effect once the app is subscribed to the WhatsApp Business Account.

Native Meta payloads vs a TXTPro-normalised format

A native Meta webhook wraps each update in entry and changes arrays, with statuses or messages nested inside value. The abbreviated example below follows the structure in Meta’s public documentation, with placeholders instead of real identifiers:

Abbreviated native Meta status update (structure from Meta’s public documentation)
{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "<BUSINESS_NUMBER>", "phone_number_id": "<PHONE_NUMBER_ID>" },
        "statuses": [{
          "id": "wamid.<MESSAGE_ID>",
          "status": "read",
          "timestamp": "1731062140",
          "recipient_id": "<CUSTOMER_NUMBER>"
        }]
      }
    }]
  }]
}

If your account receives events through TXTPro in a normalised format, a status update could instead look like a flat event shared with your other channels, as in this illustration:

Illustrative example: normalised WhatsApp status event (JSON)
{
  "event_id": "evt_example_003",
  "event_type": "message.read",
  "message_id": "msg_example_789",
  "channel": "whatsapp",
  "status": "READ",
  "timestamp": "2026-11-08T10:35:40Z"
}

In the normalised illustration, message_id would map to the wamid of the original message, timestamp would be an ISO 8601 time rather than Meta’s Unix seconds, and event_id would be a unique notification ID added for deduplication, which Meta’s native status object does not provide.

Troubleshooting WhatsApp webhooks

Common WhatsApp webhook problems
SymptomWhat to check
Callback URL will not verifyThe verify token matches exactly and the response body is the raw challenge value
Verification succeeds but no events arriveThe app is subscribed to the WhatsApp Business Account and to the messages field
Signature checks failVerify against the raw body and the correct app secret, before any JSON parsing
Read status never appearsThe customer may have disabled read receipts
Duplicate updatesRespond with 200 quickly and deduplicate on message ID plus status

Official reference: WhatsApp Business Platform documentation.

Frequently asked questions

How does WhatsApp webhook verification work?

Meta sends a GET request containing hub.mode, hub.verify_token and hub.challenge. Your endpoint checks the verify token and returns the challenge. After that, each POST should be authenticated with the X-Hub-Signature-256 header.

Why am I not receiving read statuses from WhatsApp?

Customers can turn off read receipts, so some delivered messages never produce a read update.

Will I receive Meta’s native webhook payloads through TXTPro?

It depends on how your WhatsApp account is set up. Whether you receive native Meta payloads or a normalised format is confirmed during onboarding.

Which webhook field carries incoming WhatsApp messages?

In Meta’s model, incoming messages and status updates are delivered through the messages field of the WhatsApp Business Account subscription.

Plan your API and webhook integration

Tell us which channels and events you need and where they should go. Our team will explain the integration options for your account and share the technical documentation during onboarding.

Prefer to call? +91 90304 02858 · Email info@txtpro.in

Request a demo

Tell us about your messaging requirements. Our team will walk you through the relevant channels, onboarding steps and integration options.