Receiving messages via Webhook
Webhooks are a programming mechanism that facilitates communication between applications. With webhooks, one application can send real-time data to another application when a specific event happens.
You can use the webhook to determine which endpoint we should forward the real-time data (see how to use Notifications here).
Whenever a specific event occurs, the WhatsApp Business API Client sees the event, collects the data, and immediately sends a notification (user-defined HTTP callbacks) to the webhook URL specified.
There are 3 main objects you can receive via webhooks:
messages: Used to notify you when you get a new message and what is in the new message.statuses: Used to notify you when there's a status change in a message you senterrors: When there are any out-of-band errors that occur in the normal operation of the application, this array provides a description of the error
Ensure your webhook servers can handle 3x the outgoing message traffic capacity and 1x the expected incoming message traffic capacity. For example, if you're sending 1000 messages per second with a 30% expected response rate, your servers should process up to 3000 message status webhooks and an additional 300 incoming message webhooks. See recommendations from Meta here.
Configure and load test your webhook server to handle concurrent requests with the following latency standards:
- Median latency should not exceed 250ms.
- Less than 1% of latency should exceed 1 second.
The API will attempt to re-deliver failed webhooks for up to 7 days with exponential backoff. Failure to meet these guidelines may result in delays in processing incoming messages due to the exponential backoff mechanism.
For a Webhook Notification to be considered by WhatsApp to be 'successfully delivered', the client must respond to the designated endpoint with a
HTTPS 200 OK status code. If any other status code is returned, or if the client fails to correctly set up the endpoint to accept Notifications, the WhatsApp Business API Client considers it to be a 'failed delivery' and adds the Notification to its callback queue. 360dialog also has a hard limit rule of 5 seconds for the client to return a 200 status code, after which it will register as a failed delivery.
To deploy a live webhook that can receive events from the WhatsApp Business API client, your code must have HTTPS support and a valid SSL certificate.
To ensure that your WABA service performs reliably and consistently, you should optimize the webhook to be as fast as possible. Tips for doing so include the following:
- Design your service to respond as quickly, and as close to your network speed as possible.
- Respond with a
200status code immediately after receiving a notification and storing it. The callback's payload should not be processed before responding as this can lead to unacceptable delays; instead, send the response first then (asynchronously) process the payload. - Reduce network latency by setting up your webhook server closer to 360dialog's datacenters (Central and Eastern Europe).
- Design your service to be scalable, and capable of performing well under high load/messaging volume, as increased latency may lead to your WABA number being disconnected. For further advice on scaling your service, review our page on sizing your environment based on expected throughput.
The webhook URL is a resource address to which WhatsApp Servers send notifications triggered by specific events. A suitable webhook URL must be supplied by you or by your Partner Software Provider / ISV.
You only need to set your Webhook URL once. Although you can update it or remove it at any time.
If you generate a new API KEY, the webhook URL for that number will be removed. So you must reset it using the new API-KEY.
If the webhook URL needs to be authorized by user,
USER and PASS should be provided in the header Authorization that contains Basic base64(USER:PASS). Request body example for USER=
testuser and PASS=testpassBody
{
"url": "https://www.example.com/webhook",
"headers": {
"Authorization": "Basic dGVzdHVzZXI6dGVzdHBhc3M="
}
}
Webhooks for Cloud API are configured at the WABA level. This webhook URL will receive callbacks for all Cloud API numbers associated with that WABA, but not for any On-premise numbers on the same WABA.
If there is more than one number using Cloud API in a WABA, the webhook must be configured. We strongly suggest that you use it even if there is only one Cloud API number in this WABA.
After using the
waba_webhook endpoint, the https://waba-v2.360dialog.io/configs/webhookendpoint (which only configures a webhook per phone number) will be entirely deprecated for all Cloud API numbers associated with the specific WABA. It will still work for On-Premise numbers. Use the endpoint below to set a Webhook for the whole WABA as soon as a number is onboarded with Cloud API or is moved from On-premise to Cloud API.
post
https://waba-v2.360dialog.io
/waba_webhook
Set WABA Webhook URL
Webhook URLs for Cloud API do not support "
_"(underscore) or ":xxxx"(port)in (sub)domain names.
Invalid webhook URL: https://your_webhook.example.com
Valid webhook URL: https://yourwebhook.example.com
Invalid webhook URL:https://subdomain.your_webhook.example.com:3000
Valid webhook URL: https://subdomain.yourwebhook.example.comA typical inbound notification for WABA Webhook looks like the following:
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE-NUMBER",
"phone_number_id": "PHONE-NUMBER-ID"
},
# Additional arrays and objects
"contacts": [{...}]
"errors": [{...}]
"messages": [{...}]
"statuses": [{...}]
},
"field": "messages"
}]
}]
}
Components (
contacts, errors, messages, statuses) are inside entry.changes.value.Only one webhook URL can be configured per WABA, which means that all Cloud API numbers associated with that WABA will receive their webhooks to this specific URL. To differentiate between the webhooks corresponding to different numbers, it's needed to process the data based on the payload.
Once a number moves to Cloud API and the webhook is set using the
waba_webhook logic, reverting to the previous On-premise logic (one webhook for each phone number) will not supported. Example: A customer uses the
waba_webhook endpoint with the API_KEY#1 for PHONE_NUMBER#1 linked to WABA_ID#1 to set the webhook URL as WABA_WEBHOOK#1. In this case, all Cloud API numbers under WABA_ID#1 will receive their webhook callbacks at WABA_WEBHOOK#1.From this point onward, any changes to the webhook URL configurations for this WABA should be executed by calling
waba_webhook. This applies even to numbers with a different API key under the same WABA (for example, API KEY #2), and it will work identically to the calls made with API_KEY#1.After the
/waba_webhook endpoint is operated, attempts to (v1/config/webhook) for Cloud API will result in the error 400. All other endpoints (unrelated to webhook configuration) still work exactly the same as before.
Use the GET endpoint below to check the current webhook URL:
get
https://waba-v2.360dialog.io/
waba_webhook
GET Webhook URL for multiple/single Cloud phone number in a WABA
If you are using On-premise hosting, webhooks are configured at the Phone Number level. The endpoint below will set up the webhook for a specific phone number only.
post
http://waba.360dialog.io
/v1/configs/webhook
Set Webhook URL for phone number
If the webhook URL is already set, make a GET request to retrieve the existing resource.
get
http://waba.360dialog.io
/v1/configs/webhook
GET phone number Webhook URL
When a customer sends you a message, the WhatsApp Business API client will send an HTTP POST request notification to the webhook URL with the details that are described in the following documents:
On-Premise | Cloud API |
|---|---|
Last modified 1d ago