What are Webhooks

Generally a webhook is a simple HTTP request. If you run a web application or website, you
can create your own custom endpoints. Then you can set url of your endpoint as the webhook
url of your instance. In addition, you need to subscribe to at least one event.
For example, you can subscribe to the message event. As soon as one of the subscribed events
happen (for example if someone sends a message to you), the instance will make a HTTP request
to the given webhook url. The body of the request contains the event data. Now you are able to
directly react to specific events and run your business logic in realtime based on these events.

Webhook Request

HTTP Method


Request Headers

User-AgenteazeWA Webhook User Agent

Request Body

    "event": "<event_name>",
    "instanceId": "33",
    "data": {
        // Depends on the specific event

Expected Response

After you have received the request of the webhook, you should send a response status code
>= 200 and < 300. Otherwise, we will track your response as an error, but we will not send
this request again, if we receive a 3xx, 4xx or 5xx status code.

If a send request times out because your server is down or for some other reasons, we send this
request again with a delay of round about 3000 ms until we receive any response.

Create a Webhook

Node.js example

npm install express --save
const express = require('express');
const app = express();
const port = 3000;

// we protect our endpoint with a security token
// we highly recommend you to use a individual security token per instance
// so that you are able to compare the security token with the instanceId of the request
const securityTokens = {
    33: "ETBu4KVOMXT2KCL1t9SGRIJ7Ra8zEPFM60QINdAp3GjD5Bw",


app.post('/webhooks/whatsapp/:security_token', async (req, res) => {
    const securityToken = req.params.security_token;
    const body = req.body;

    const instanceId = body.instanceId;
    const eventName = body.event;
    const eventData = body.data;

    if (securityToken == null || instanceId == null || eventName == null || eventData == null) {
        console.log('Invalid request');

    // check if the security token and the instanceId match in our records
    if (securityTokens[instanceId] !== securityToken) {
        console.log('Authentication failed');

    // the request is validated and the requester authenticated
    if (eventName === 'message') {
        console.log('Handle message event...');
        const messageData = eventData.message;
        const messageType = messageData.type;
        if (messageType === 'chat') {
            const messageSenderId = messageData.from; // unique WhatsApp ID. We need to parse it to get the real phone number
            const messageCreatedAt = new Date(messageData.timestamp * 1000); //because the timestamp is in seconds
            const messageContent = messageData.body;

            // this is the phone number of the message sender
            // it starts with the country code (without a leading + or leading 00)
            const messageSenderPhoneNumber = messageSenderId.replace('@c.us', '');

            //run your business logic: someone has sent you a WhatsApp message

    } else {
        console.log('Cannot handle this event: ' + eventName);

app.listen(port, () => {
    console.log(`Listing on port ${port}`);

Set the Webhook and subscribe to Events

Please take a look at the Update Instance endpoint. You can
use this endpoint directly after creating a new instance to set the webhook and to subscribe to events
or every time you want to change the webhook url or change the subscribed events.

In relation to our Node.js example, you would use


as the webhook url and subscribe to the message event.

Available Events

Event NameDescription
messageFired when you receive a message. The event contains all data related to the message like content and sender
loading_screenFired when your instance is loading
qrFired when a new QR code is generated while your instance is in QR status.
authenticatedFired when the connection is made
auth_failureFired if authentication fails
readyFired as soon as everything is ready
disconnectedFired when you disconnect your instance
message_createFired when a new message is created. Applies to both, sent and received messages.
message_revoke_everyoneFired if a message was deleted for everyone
message_revoke_meFired if a message was only deleted for you
message_ackFired when a message was read or received
message_reactionFired when a reaction is sent, received, updated or removed
media_uploadedFired when a new media file was upload successfully when sending a message
group_joinFired when someone is added or joined a group chat
group_leaveFired when someone is removed or left a group chat
group_updateFired when the group information is updated
change_stateFired as additional event when your connection status changes
callFired on incoming calls - calls cannot be handled by the API.