Meta WhatsApp

The Meta WhatsApp webhook receives delivery status updates and incoming messages from Meta’s WhatsApp Cloud API. It handles both the webhook verification handshake and ongoing event notifications.

Endpoints

Event notifications

POST /api/rpc/webhooks/meta/whatsapp

Webhook verification

GET /api/rpc/webhooks/meta/whatsapp

Meta calls the GET endpoint during webhook setup to verify ownership. The platform validates the verify token and returns the challenge.

Query Parameter	Description
`hub.mode`	Must be `subscribe`
`hub.verify_token`	Must match `META_WHATSAPP_VERIFY_TOKEN`
`hub.challenge`	Challenge string returned as the response

Signature validation

Meta signs webhook requests using HMAC-SHA256.

Header	Description
`X-Hub-Signature-256`	`sha256=<hmac_hex>`

The signature is computed over the raw request body using your app secret. Configure this using the META_WHATSAPP_APP_SECRET environment variable.

Supported statuses

Meta Status	Platform Event	Description
`sent`	`whatsapp_sent`	Message sent
`delivered`	`whatsapp_delivered`	Message delivered to recipient
`read`	`whatsapp_read`	Recipient read the message
`failed`	`whatsapp_failed`	Message failed

Event structure

Meta sends events in a nested structure. The platform extracts statuses from entry → changes → value → statuses. A single webhook call can contain multiple events.

Metadata

Field	Description
`conversationId`	WhatsApp conversation ID
`pricingModel`	WhatsApp pricing category
Error details	Extracted from `statusData.errors` array

Response

{
  "success": true,
  "processed": 3,
  "duplicates": 0,
  "errors": 0
}

Setup

In the Meta Developer Dashboard, go to your WhatsApp app’s Webhooks configuration.
Set the Callback URL to your platform’s Meta WhatsApp webhook endpoint.
Set the Verify token to a secure random string.
Set these environment variables:
- META_WHATSAPP_VERIFY_TOKEN — the verify token you chose
- META_WHATSAPP_APP_SECRET — your WhatsApp app secret from Meta
Subscribe to the messages webhook field.

Twilio WhatsApp — alternative WhatsApp integration via Twilio
Gupshup — alternative WhatsApp integration via Gupshup
Webhooks overview — how webhooks work