Webhooks

This documentation describes how to setup webhooks for the WhatsApp Business API.

Introduction

Webhooks are one of a few ways web applications can communicate with each other. 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 to which endpoint we should forward the real-time data (or also known as Notifications). Whenever that trigger 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 in the application settings. Some example events are: - updating the status of sent messages - indicating when you receive a message

Only HTTPS webhook URLs on port 443 are valid.

It is important that your webhook returns an HTTPS 200 OK response to any notifications. Otherwise we consider that notification as failed and try again after a short delay.

Never process incoming messages and notifications in the callback handler!

Only use asynchronous handling of callbacks - acknowledge immediately after receiving the callback, then process.

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.

1. Set Webhook URL

The webhook URL is a URL where the WhatsApp Business API sends the notifications to, triggered by specific events.

The webhook URL can either be: - the URL from your own application - or the partner

Request Schema:

post
submit an entity to the specified resource.

/v1/configs/webhook
Send a POST request and store the URL from the response.
Request
Response
Request
Headers
Content-Type
required
string
application/json
D360-API-KEY
required
string
Body Parameters
URL
optional
string
www.example.com/webhook
Response
200: OK
This class of status codes indicates the action requested by the client was received, understood, and accepted.
{
"url": URL,
"headers": {
"header_1": string,
"header_2": string
}
}
400: Bad Request
The 400 Bad Request Error is an HTTP response status code that indicates that the server was unable to process the request sent by the client due to invalid syntax.
{
"meta": {
"success": false | true,
"http_code": 400,
"developer_message": string,
"details": [
string
]
}
}
500: Internal Server Error
The HTTP status code 500 is a generic error code. It means that the encounterted an unexpected condition that prevented it from fulilling the request.
{
"meta": {
"success": false,
"http_code": 500,
"developer_message": string
}
}
Body
Body
{
"url": URL,
"headers": {
"header_1": string,
"header_2": string
}
}

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
Body
{
"url": "https://www.example.com/webhook",
"headers": {
"Authorization": "Basic dGVzdHVzZXI6dGVzdHBhc3M="
}
}

2. Get Webhook URL

If the webhook URL is already set up as described above, you can send a GET request to get the URL.

Request Schema:

get
requests a representation of the specified resource.

/v1/configs/webhook
Request
Response
Request
Path Parameters
Content-Type
required
string
application/json
D360-API-Key
required
string
unique API-Key
Response
200: OK
This class of status codes indicated the action requested by the client was received, understood and accepted.
{
"url": URL,
"headers": {
"header_1": string,
"header_2": string
}
}
400: Bad Request
The 400 Bad Request Error is an HTTP response status code that indicates that the server was unable to process the request sent by the client due to invalid syntax.
{
"meta": {
"success": false | true,
"http_code": 40X,
"developer_message": string,
"details": [
string
]
}
}
500: Internal Server Error
The HTTP status code 500 is a generic error response. It means that the server encountered an unexpected condition that prevented it from fulfilling the request.
{
"meta": {
"success": false,
"http_code": 500,
"developer_message": string
}
}

Example:

Request
Response
Request
D360-API-KEY: adafABC43
Content-Type: application/json
Response
{
"url": "https://www.example.com/webhook",
"headers": {
"Authorization": "Basic dGVzdHVzZXI6dGVzdHBhc3M="
}
}