Design a Stable Webhook Receiving Endpoint

Ensure your service quickly responds to Web-hook Notifications

In order to send and receive messages using 360dialog's API, you will need to set up a server that handles Web-hook Notifications from WhatsApp.

A web-hook is a mechanism that enables communication between two different applications or systems in real-time. With a web-hook, an application can send a notification (usually in the form of an HTTP POST request) to another application whenever a particular event occurs. This allows for the automatic exchange of information between the two applications without the need for continuous polling or user intervention.

WhatsApp Webhook Notifications

The WhatsApp Business API Client sends Web-hook Notifications to the client-designated webhook URL.

For further information, review our guide on receiving messages via webhook.

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

Important: We recommend designing your service to respond as quickly as possible, or as close to your network speed to avoid any issues. Furthermore, the service should be scalable, and capable of performing well under high load/messaging volume, as an increased latency may lead to your WABA number being disconnected.

For further advice on designing your service for scale, review our page on sizing your environment based on expected throughput.

Webhooks can be handled synchronously or asynchronously. We would recommend following the asynchronous approach for the reasons below.

The risk of synchronously handling Webhook Notifications

Designing a synchronous Webhook Notification handler typically involves these steps:

1) The Server receives the Webhook Notification.

2) The Server begins to process the Notification payload.

3) The Sever finishes processing the Notification payload.

4) The Server returns a 200 'status' response.

The problem with this design is that the response time is blocked by the processing time (step 2) , which may not be consistently achievable under higher loads, especially if step 2 is complex (such as making a complex SQL query, or a call to another API).

To solve this problem, it is advisable to decouple the storage of the webhook from the processing of the payload by implementing an asynchronous flow.

Asynchronous Handling of Webhook Notifications

Asynchronous refers to a computing process or communication method in which tasks or requests are executed independently and in a non-blocking manner, allowing the system to perform certain tasks simultaneously. In an asynchronous system, tasks or events can be initiated and run independently of one another, without having to wait for the previous task to complete before starting the next one.

An asynchronous approach for the Webhook Notification Handler may involve the following steps:

1) The Server receives Webhook Notification.

2) The Server adds the Notification payload to a message queue.

3) The Server returns a 200 status response.

4) (Asynchronously) The Server processes the stored Notification.

Because the payload processing is conducted in a non-blocking manner, the server can send the response to WhatsApp almost immediately after storing the payload. This guarantees a consistent response time, improving the stability of the WhatsApp number.

Pseudocode Example of an Asynchronous Webhook Notification Handler

When a request is received, the webhook_handler function will simply add the request to the message queue, and return a 200 status response.

from aiohttp import web
import message_queue

async def webhook_handler(request):
    message_queue.add(request.json)
    return web.Response(status=200)

app = web.Application()
app.add_routes([web.get('/webhook_handler', webhook_handler)])
web.run_app(app)

A separate, non-blocking component retrieves messages from the queue and processes them, without the pressure of any time limits.

import message_queue

async def process_payload(message):
    print("Processing payload...")
    # processing ...
    print("Payload processed: ", message)

def main():
    for message in message_queue.get():
        process_payload(message)