English
Account Setup
Webhooks
This documentation describes how to setup webhooks for the WhatsApp Business API.

Introduction

Webhooks is a mechanism which enables applications can communicate with each other programmatically. It allows you to send real-time data from one application to another whenever a given event occurs. You can use the webhook to determine which endpoint we should forward the real-time data (aka Notifications). 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 sent.
  • errors: 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.
It is essential that your Webhook URL returns an HTTPS 200 OK response to notifications. Otherwise the WhatsApp Business API client considers that notification as failed and tries again after a delay.
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.
Only use asynchronous handling of webhooks
Do not process incoming messages and notifications in the webhook handler; acknowledge immediately after receiving the webhook (with status 200), then you can process the data.
All incoming messages will automatically shown as delivered (two grey ticks). To make them appear as read (two colored ticks), you have to mark the messages as read.

Webhook URL

The webhook URL is a resource address to which the WhatsApp Servers sends notifications, which are 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.
You must set a Webhook URL once per number.
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.

Schema

post
http://[base-url]
/v1/configs/webhook
Set Webhook URL
Body
1
{
2
"url": URL,
3
"headers": {
4
"header_1": string,
5
"header_2": string
6
}
7
}
Copied!

Example setting webhook with Basic Auth:

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=testpass
Body
1
{
2
"url": "https://www.example.com/webhook",
3
"headers": {
4
"Authorization": "Basic dGVzdHVzZXI6dGVzdHBhc3M="
5
}
6
}
Copied!

Get Webhook URL

If the webhook URL is already set, make a GET request to retrieve the existing resource.

Schema

get
http://[base-url]
/v1/configs/webhook
Retrieve existing webhook URL

Example:

Request
Response
1
D360-API-KEY: adafABC43
2
Content-Type: application/json
Copied!
1
{
2
"url": "https://www.example.com/webhook",
3
"headers": {
4
"Authorization": "Basic dGVzdHVzZXI6dGVzdHBhc3M="
5
}
6
}
Copied!

Important links

Components - WhatsApp Business Platform - Documentation - Facebook for Developers
Facebook for Developers
Detailed components