Webhooks 🪝

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

POST

Request Headers

Name	Value
Content-Type	application/json
User-Agent	eazeWA Webhook User Agent

Request Body

JSON

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

Shell

npm install express --save

JavaScript

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.use(express.json());

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');
        res.sendStatus(400);
        return;
    }

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

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

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

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

http://your-domain.com:3000/webhooks/whatsapp/ETBu4KVOMXT2KCL1t9SGRIJ7Ra8zEPFM60QINdAp3GjD5Bw

as the webhook url and subscribe to the message event.

Available Events

Event Name	Description
message	Fired when you receive a message. The event contains all data related to the message like content and sender
loading_screen	Fired when your instance is loading
qr	Fired when a new QR code is generated while your instance is in QR status.
authenticated	Fired when the connection is made
auth_failure	Fired if authentication fails
ready	Fired as soon as everything is ready
disconnected	Fired when you disconnect your instance
message_create	Fired when a new message is created. Applies to both, sent and received messages.
message_revoke_everyone	Fired if a message was deleted for everyone
message_revoke_me	Fired if a message was only deleted for you
message_ack	Fired when a message was read or received
message_reaction	Fired when a reaction is sent, received, updated or removed
media_uploaded	Fired when a new media file was upload successfully when sending a message
group_join	Fired when someone is added or joined a group chat
group_leave	Fired when someone is removed or left a group chat
group_update	Fired when the group information is updated
change_state	Fired as additional event when your connection status changes
call	Fired on incoming calls - calls cannot be handled by the API.