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

WhatsApp Web-hook Response Requirements

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.

Recommendations

We recommend that you review our best practices when implementing your solution.

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 200 status 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.

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.

If the WABA is registered in On-premise API

If you are using On-Premise hosting, use the base-url waba.360dialog.io.

If the WABA is registered in Cloud API

If you are using Cloud API hosting, the endpoint is expected to work in the same way, however, you must use the base-url waba-v2.360dialog.io.

Set Webhook URL

Set Webhook URL

POST http://[base-url]/v1/configs/webhook

Send a POST request and store the URL from the response.

Request example

{

"url": URL,

"headers": {

"header_1": string,

"header_2": string

}

}

Headers

Name	Type	Description
Content-Type	string	application/json
D360-API-KEY	string

Request Body

Name	Type	Description
URL	string	www.example.com/webhook

200 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 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.

500 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.

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="
  }
}

Get Webhook URL

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

Retrieve existing webhook URL

GET http://[base-url]/v1/configs/webhook

Request example

D360-API-KEY: adafABC43

Content-Type: application/json

Path Parameters

Name	Type	Description
Content-Type	string	application/json
D360-API-Key	string	unique API-Key

200 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 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.

500 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.

Receiving notifications for incoming messages

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
Inbound Message Notifications	Inbound Message Notifications
Inbound Media Message Notifications	Inbound Media Message Notifications
Inbound Replies to Sent Messages	Inbound Replies to Sent Messages
Inbound System Messages	Inbound System Messages
Outbound Message Status Notifications	Outbound Message Status Notifications

Make sure to check out the Best Practices docs for more information.