Overview
Webhooks let you receive real-time notifications when customers send you WhatsApp messages and when your outbound messages are delivered, read, or fail. Configure your webhook URL through the WABA webhook settings in the Telnyx API or Portal.
Setting Up Webhooks
Via the Telnyx Portal
Go to Messaging → WhatsApp
Select your WhatsApp Business Account
Navigate to the webhook configuration section
Enter your webhook URL (must be HTTPS)
Save the configuration
Via the API
Use the WABA webhook configuration endpoint to set your webhook URL programmatically. You can also specify a webhook_url per message when sending via POST /v2/messages/whatsapp.
Webhook Events
Inbound Messages
When a customer sends you a message, you receive a webhook with the message content. The payload includes:
Sender's phone number
Message type (text, image, video, document, audio, location, contacts, interactive reply)
Message content (text body, media URL, location coordinates, etc.)
Timestamp
Message ID (for replying with context)
Delivery Status Updates
For each outbound message, you receive status webhooks as the message progresses:
Status | Meaning |
| Message accepted by WhatsApp |
| Message delivered to recipient's device |
| Recipient opened/read the message |
| Message could not be delivered |
Delivery status webhooks include the billing_type field (e.g., whatsapp_marketing, whatsapp_utility, whatsapp_service) so you can track costs.
Webhook Requirements
HTTPS — Your endpoint must use HTTPS with a valid SSL certificate
200 response — Return a 200 status code within 5 seconds to acknowledge receipt
Idempotency — You may receive the same webhook multiple times; handle duplicates gracefully using the message ID
Testing Webhooks
For development, you can use tools like ngrok or Hookdeck to expose a local endpoint to the internet and inspect incoming webhook payloads.
Related Resources