Receiving messages

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.

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 to that account.

There are 3 main objects you can receive via the Number Webhook:

• 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

Webhook Response Requirements

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 more information about throughput 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.

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.

Set Webhook URL

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 the client or by the Partner Software Provider / ISV.

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.

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

Set Webhook URL for phone number

Previously, webhook for Cloud API numbers could only be configured at a WABA Level. This limitation has been lifted and, from April, 2024, the Set Webhook URL for phone number endpoint can set Webhook at a phone number level, regardless of the integration type.

We recommend using this configuration to ensure the highest performance possible.

Webhook URLs or headers for Cloud API does 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.com

If you are still using On-premise API, webhooks are configured only at the Phone Number level. In this case, the endpoint will be https://waba.360dialog.io/v1/configs/webhook

POST https://waba-v2.360dialog.io/v1/configs/webhook

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

Request example

{
  "url": "string",
  "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": "https://example.com",
  "headers": {
    "header_1": "value1",
    "header_2": "value2"
  }
}

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.

{
  "meta": {
    "success": false | true,
    "http_code": 400,
    "developer_message": string,
    "details": [
      string
    ]
  }
}

500 The HTTP status code 500 is a generic error code. It means that the encounterted an unexpected condition that prevented it from fulfilling the request.

{
  "meta": {
    "success": false,
    "http_code": 500,
    "developer_message": string
  }

Set Webhook per WABA (Cloud API)

Webhooks for Cloud API can be set at the WABA level, although this configuration is not recommended since it can decrease the messaging performance of the channels.

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.

POST https://waba-v2.360dialog.io/waba_webhook

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

Request example

curl --location 'https://waba-v2.360dialog.io/waba_webhook' \
--header 'Content-Type: application/json' \
--header 'D360-API-KEY: ' \
--data '{
    "url": "string",
    "headers": {
        "header_1": "string"
    },
    "override_all": "boolean"
}'

When this endpoint is used with the override_all parameter set to false, it configures the supplied webhook for Cloud API numbers missing a specific phone number webhook setting. If override_all is true, the webhook applies across all Cloud API numbers within the WABA.

Headers

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

Request Body

Name	Type	Description
URL*	string	www.example.com/webhook
headers*	string
override_all	boolean	Optional. Indicates if the supplied webhook should override current phone number webhooks for all phone numbers belonging the same WABA Default value isfalse

200 This class of status codes indicates the action requested by the client was received, understood, and accepted.

{
    "message": "Webhook will be set for waba_id: 123065260884961"
}

//This message means that the Webhook URL will be set within the next 15-20 seconds. 
//Please confirm by fetching the current webhook URL before messaging.

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.

{
  "meta": {
    "success": false | true,
    "http_code": 400,
    "developer_message": string,
    "details": [
      string
    ]
  }
}

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.

{
  "meta": {
    "success": false,
    "http_code": 500,
    "developer_message": string
  }
}

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

Delivery prioritization

Cloud API allows configuring webhooks at a Phone Number and WABA Webhook level. For callback delivery, webhooks are prioritized as below:

• Primary is Phone Number Webhook: This is the preferred route. If set, it overrides any other webhook configuration for callbacks.

• Secondary is WABA Webhook: This route is used for callback delivery only if the primary phone number webhook is not configured.

• Fallback: No Webhook Configured - If neither webhook is set, the system will return an empty response when attempting callbacks.

Get Webhook URL

Get phone number Webhook URL

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

GET http://waba-v2.360dialog.io/v1/configs/webhook

GET http://waba.360dialog.io/v1/configs/webhook

Request example

D360-API-KEY: {{api_key}}

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.

{
  "meta": {
    "success": false | true,
    "http_code": 400,
    "developer_message": string,
    "details": [
      string
    ]
  }
}

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.

{
  "meta": {
    "success": false,
    "http_code": 500,
    "developer_message": string
  }
}

Get WABA Webhook URL

Use the GET endpoint below to check the current WABA webhook URL:

GET https://waba-v2.360dialog.io/waba_webhook

Request example

curl --location 'https://waba-v2.360dialog.io/waba_webhook'
--header 'd360-api-key: '

Headers

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

200 This class of status codes indicates the action requested by the client was received, understood, and accepted.

{
    "waba_id": 123456,
    "numbers_on_this_waba": ["12345678910", "11223344"],
    "url": "URL",
    "headers": {
        "key": "HEADERS"
    }
}

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.

{
  "meta": {
    "success": false | true,
    "http_code": 400,
    "developer_message": string,
    "details": [
      string
    ]
  }
}

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.

{
  "meta": {
    "success": false,
    "http_code": 500,
    "developer_message": string
  }
}

Receiving notifications for incoming messages

When a customer replies, or sends a message to the business, the WhatsApp Business API client will send an HTTP POST request notification to the number webhook URL with the details described in our documentation below:

Webhook events and notifications