Twilio WhatsApp

The Twilio WhatsApp webhook receives delivery status callbacks for WhatsApp messages sent through Twilio’s WhatsApp Business API. These updates track whether messages were sent, delivered, read, or failed.

Endpoint

POST /api/rpc/webhooks/twilio/whatsapp

Signature validation

Twilio signs webhook requests using HMAC-SHA1, the same method used for SMS callbacks.

Header	Description
X-Twilio-Signature	HMAC-SHA1 signature (base64)

Configure the auth token using the TWILIO_WEBHOOK_AUTH_TOKEN environment variable.

Supported statuses

Twilio Status	Platform Event	Description
sent	whatsapp_sent	Message sent to WhatsApp
delivered	whatsapp_delivered	Message delivered to recipient
read	whatsapp_read	Recipient read the message
failed	whatsapp_failed	Message failed to send
undelivered	whatsapp_failed	Message could not be delivered
queued	—	Skipped (message queued)
sending	—	Skipped (message being sent)

Payload fields

The callback is sent as form-encoded data. Phone numbers include the whatsapp: prefix, which the platform strips automatically.

Field	Description
MessageSid	Twilio’s unique message ID
MessageStatus	Current delivery status
To	Recipient (with whatsapp: prefix)
From	Sender (with whatsapp: prefix)
ErrorCode	Twilio error code (if failed)
ErrorMessage	Error description (if failed)
AccountSid	Your Twilio account ID
ChannelPrefix	whatsapp

Response

{
  "success": true,
  "processed": 1
}

Setup

1. In your Twilio console, configure the Status Callback URL on your WhatsApp sender.
2. Set the URL to your platform’s Twilio WhatsApp webhook endpoint.
3. Set the TWILIO_WEBHOOK_AUTH_TOKEN environment variable to your Twilio auth token.

Related pages

• Twilio SMS — SMS delivery status via Twilio
• Meta WhatsApp — alternative WhatsApp integration via Meta
• Webhooks overview — how webhooks work