Incoming Messages
Receive and manage real-time WhatsApp message notifications via webhooks
Incoming message webhooks deliver real-time notifications when your recipients reply, enabling immediate responses and interactive conversations through WhatsApp.
The Incoming Messages system provides a robust webhook infrastructure that enables your application to receive and process WhatsApp messages from your recipients in real-time. This guide covers how to configure, manage, and handle incoming message webhooks.
Overview
Webhooks are HTTP callbacks that deliver notifications to your server whenever specific events occur - in this case, when recipients reply to your WhatsApp messages. Benefits include:
- Real-time processing of customer responses
- Seamless integration with your existing systems
- Automated workflows triggered by customer messages
- Enhanced customer experience through timely interactions
Try it in the API Reference
Explore the Webhook Management API and start receiving incoming messages
Webhook Configuration
Managing Endpoints
Access Webhook Settings
Navigate to the Developer section in your dashboard sidebar to manage webhook configurations.
Configure Endpoint
Add a new webhook URL where you want to receive incoming message notifications.
Set Up Authentication
We recommend implementing signature verification to ensure webhook security.
Test Your Endpoint
Use the test feature to verify your webhook is properly receiving and processing events.
Endpoint Requirements
All webhook endpoints must be publicly accessible via HTTPS and configured to accept POST requests with JSON payloads. HTTP endpoints are not supported in production environments.
Your webhook endpoint must:
- Accept HTTP POST requests
- Process JSON payloads
- Return a 2xx status code within 10 seconds
- Implement idempotency handling (see best practices below)
Webhook Payload
When a user replies to your WhatsApp message, we’ll send a POST request to your configured endpoint with a detailed payload.
Sample Payload
Payload Fields
Type of event, always “incoming_message” for incoming messages
Unique identifier for the event, use this for deduplication
ISO 8601 timestamp when the event occurred
API version identifier
Webhook Management API
You can programmatically manage your webhook endpoints using our API.
List Webhook Endpoints
Retrieve all configured webhook endpoints for your account.
Create Webhook Endpoint
Register a new webhook endpoint to receive incoming message notifications.
Webhook Security
Always verify webhook signatures to ensure the authenticity of incoming requests. This prevents malicious actors from sending fraudulent events to your endpoint.
Signature Verification
Every webhook request includes a signature in the X-Webhook-Signature
header. Verify this signature by:
- Extract the
X-Webhook-Signature
header value - Compute an HMAC-SHA256 signature using your webhook secret and the raw request body
- Compare the computed signature with the header value
Best Practices
Idempotency
Implement idempotency key checks to prevent duplicate processing of events. Use the event_id
field to detect and handle retries.
Graceful Error Handling
Design your webhook handler to gracefully process unexpected payload structures or event types. This ensures compatibility with future API updates.
Quick Response
Always respond quickly with a 2xx status code, then process the webhook asynchronously. Responses taking longer than 10 seconds may cause webhook delivery retries.
Multiple Endpoints
Consider configuring multiple webhook endpoints for different environments (development, staging, production) or different types of processing.
Handling Media Files
When receiving media messages:
- Download the media file from the URL provided in the webhook as soon as possible
- Media URLs expire after 24 hours
- Verify the SHA-256 hash to ensure file integrity
- Store media files securely in your system
Rate Limiting and Quotas
Testing Webhooks
Test your webhook implementation before going live:
- Create a test webhook endpoint using a service like webhook.site or Beeceptor
- Configure this test URL in your webhook settings
- Send a test WhatsApp message to trigger the webhook
- Inspect the payload to understand the data structure
- Implement proper handling in your application
Always test your webhook implementation thoroughly in a development environment before configuring production endpoints.
Troubleshooting
FAQs
Need help?
Our support team is available 24/7 to assist with webhook setup, event handling, or any other questions.
Enhanced Webhook System
- Added signature verification for improved security
- Extended media file expiration to 24 hours (previously 1 hour)
- Improved retry logic for failed webhook deliveries
- Added support for multiple endpoints per account