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

info

Only HTTPS webhook URLs on port 443 are valid.

important

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.

info

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.

info

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.

Body Parameters(Optional)

Content-Type*	string	application/json
WHIZARD-KEY*	string
URL	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 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

{  "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

{  "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.

GET

requests a representation of the specified resource.

/v1/configs/webhook

Request#

Content-Type*	`string`	application/json

WHIZARD-KEY*	`string`	`unique API-Key`

Request

WHIZARD-KEY: adafABC43Content-Type: application/json

Response#

Response

{  "url": "https://www.example.com/webhook",  "headers": {    "Authorization": "Basic dGVzdHVzZXI6dGVzdHBhc3M="  }}

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

  WHIZARD-KEY: adafABC43  Content-Type: application/json

  {  "url": "https://www.example.com/webhook",      "headers": {          "Authorization": "Basic dGVzdHVzZXI6dGVzdHBhc3M="      }  }