Webhook is used to process incoming events, asynchronous request responses, and error information. For example, when an incoming message is received in the messenger, a POST request is sent to the configured webhook:

{
  "id":18,
  "whatsapp_id":"191b80a9238",
  "event_action":"message",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id" : "3EB0436AE1E682FF3A37",
       "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79991112233@c.us",
       "to":"79999999999@c.us",
       "isForwarded":false
    }
  }
}

To confirm successful event receipt, your webhook must return a JSON object containing the incoming event identifier and status OK.

{
  "result" : "OK",
  "id" : 18
}

If the system does not receive a valid response, it retries the request 3 times every 20 seconds.

To set a Webhook handler URL, open your account dashboard, choose the linked WhatsApp block, click the 3 dots, then click edit.

In the opened window, specify the URL to your Webhook handler script.

Click “Save”.

To enable or disable WebHook via API, use the set-hook method. Send a POST request to:

https://whatsgate.org/api/v1/set-hook

Request body:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "callback": "https://callback.my/script.handler"
}

• WhatsappID - WhatsApp identifier in the system
• callback - URL of incoming events handler

Successful response object

{
  "result": "OK"
}

• ready
• message
• sent
• ack
• disconnect
• error
• create

This event is sent after authorization, when the client is fully ready to send and receive messages. Session status changes from AUTH to READY. Field event_action contains “ready”. Field event_data contains authorized account data: number and name.

• pushname - client's name in messenger
• number - authorized phone number
• id - WhatsApp identifier in @c.us format

{
  "id":19,
  "whatsapp_id" : "191b80a9238",
  "event_action" : "ready",
  "event_date" : "2023-01-24 18:29:37",
  "status_code" : null,
  "event_data" :
  {
    "pushname": "vasya",
    "number" : "79991234567",
    "id" : "79991234567@c.us"
  }
}

This event is sent for any incoming message in a chat or group. Field event_action contains “message”. Field event_data contains a message object.

{
  "id":18,
  "whatsapp_id":"191b80a9238",
  "event_action":"message",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79991112233@c.us",
       "to":"79999999999@c.us",
       "isForwarded":false
    }
  }
}

This event is sent after successful message delivery when an asynchronous send command was used.

Field event_action contains “sent”. Field event_data contains the delivered message object.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"sent",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79999999999@c.us",
       "to":"79991112233@c.us",
       "isForwarded":false
    }
  }
}

This event is sent when a message status changes in a chat or group. Field event_action contains “ack”. Field event_data contains the message object whose status changed. Message status is in message field ack and can be: 1 - sent, 2 - delivered, 3 - read.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"ack",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79999999999@c.us",
       "to":"79991112233@c.us",
       "isForwarded":false
    }
  }
}

This event is sent when the client disconnects and closes. This happens when you remove the client from your account dashboard or revoke the link in the WhatsApp mobile app. Field event_action contains “disconnect”. Field event_data contains an object with field reason describing the disconnect cause.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"disconnect",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "reason": "Client disconnected"
  }
}

This event is sent when any error occurs. For example, when you try to send asynchronously to a number outside your contact list on the Light plan. Field event_action contains “error”. Field event_data contains an object describing the error.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"error",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "error":"Specified number not in your contact list"
  }
}

This event is sent for any outgoing message in a chat or group. It lets you track sent messages via webhook, including messages sent from the mobile client or other linked applications.

Field event_action contains “create”.

Field event_data contains a message object.

{
  "id":18,
  "whatsapp_id":"191b80a9238",
  "event_action":"create",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"true_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79991112233@c.us",
       "to":"79999999999@c.us",
       "isForwarded":false
    }
  }
}

{
   "_id":"3EB0436AE1E682FF3A37",
   "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
   "ack":1,
   "hasMedia":false,
   "mediaKey":"",
   "body":"212",
   "type":"chat",
   "timestamp":1662575377,
   "from":"79999999999@c.us",
   "to":"79991112233@c.us",
   "isForwarded":false,
   "quoted": {
       "_id": "3EB07621A4D08F9F59E0",
       "from": "79537226631@c.us",
       "type": "chat",
       "body": "Hello!"
   }
}

Message object fields:

• _id - message identifier in WhatsApp.
• id - WhatsApp message identifier that can be passed in the “quote” field to mark a message as a reply.
• ack - (int) status flag showing message state: 1 - sent, 2 - delivered, 3 - read
• hasMedia - flag indicating whether message contains a media file
• mediaKey - media file key used in get-media to fetch media.
• body - message text
• type - message type
• timestamp - message date in Unix timestamp format
• from - sender identifier
• to - recipient identifier
• isForwarded - indicates whether the message was forwarded from another chat
• quoted - if this message quotes (replies to) another message, quoted contains the quoted message object.
  • _id - quoted message identifier
  • from - quoted message author identifier
  • type - quoted message type
  • body - quoted message text

<?php
 
//buffer output
ob_start();
 
var_dump('----------------------' . date('d.m.Y H:i:s') . '----------------');
 
//extract request data
$input = file_get_contents('php://input');
$input_data = json_decode($input, true);
 
var_dump($input_data);
 
if($input_data['event_action'] == 'message') {
    //@TODO process incoming message
 
}
 
if($input_data['event_action'] == 'ack') {
 
    //@TODO process delivery or read status
 
    if($input_data['event_data']['message']['ack'] == 2) {
        //@TODO delivered
    }
    if($input_data['event_data']['message']['ack'] == 3) {
        //@TODO read
    }
}
 
//save log
$fo = fopen('webhook.log', 'a');
fwrite($fo, ob_get_clean());
fclose($fo);
 
//build and output response
$answer_data = [
    'id' => $input_data['id'],
    'result' => 'OK'
];
 
echo json_encode($answer_data);
?>