How To Use Webhooks For WhatsApp Messages

Process automated inbound and outbound webhook message notifications through your WhatsApp number. Let’s cover the multiple use cases with examples.

Introduction to Webhooks

Webhooks are an incredibly useful and efficient way to implement event observability and integration in software systems.

In essence, Webhooks provide a communication mechanism where a server-side application can notify a third-party server-side application when a new event that the consumer application might be interested in, has occurred on the system.

Webhooks operate on the concept of “event reaction” (don’t call me, I’ll call you if I have something new), thus avoiding the need to constantly poll the server-side application. Therefore, rather than doing your consumer application constantly polling the server-side application to check for new events, the server-side application calls your application by invoking a client-provided webhook URL via HTTP protocol anytime the server-side has something new to report.

🤩 🤖 Wassenger is a complete communication platform and API solution for WhatsApp. Explore more than 100+ API use cases and automate anything on WhatsApp by signing up for a free trial and getting started in minutes!

A clear and well-defined use case would be precisely a WhatsApp conversation, where you don’t know when a user will send you a message, yet you need to process that message right after is received and possibly reply to the user with another message. This can be achieved efficiently and simply by using Webhooks between your software and Wassenger. Webhooks are the foundation for creating automated conversations such as chatbots.

Webhooks can operate with any software no matter the language you use, as the common protocol would be HTTP(S) for communication and JSON format for data serialization.

Find here a general introduction to Webhooks.

Useful resources

• API documentation for Webhooks
• Introduction to Webhooks
• Webhook Free Service for Testing & Debugging
• Expose your local server to the Internet using Ngrok
• Handling Webhook Requests in PHP
• Webhook server in Go

For production integrations, it is required to use HTTPS instead of HTTP since communication would be end-to-end secure and encrypted.

Webhook events

This a list of the different supported webhook events that can notify your system based on different scenarios:

• [message:in:new](https://app.wassenger.com/help/webhooks#when-a-new-inbound-message-is-received): On every new incoming message sent by users or groups to your number (only for Platform plans)
• [message:out:new](https://app.wassenger.com/help/webhooks#when-a-new-outbound-message-is-successfully-delivered): On every outbound message delivered from the connected WhatsApp number to other users (only for Platform plans)
• [message:out:ack](https://app.wassenger.com/help/webhooks#when-a-sent-message-is-read-or-played-by-the-user): On every outbound message status update: received or read by the user (only in Platform Business and Enterprise plans)
• [message:out:failed](https://app.wassenger.com/help/webhooks#when-a-message-delivery-fails): On every failed message delivery such as max retries exceeded, invalid media or target phone number not found
• [group:update](https://app.wassenger.com/help/webhooks#when-a-group-is-updated): On every group update: when a group subject is updated, when participant(s) are added or removed, when the group permissions are updated, etc.
• [channel:in](https://app.wassenger.com/help/webhooks#when-a-new-message-is-received-on-the-channels): On every newly received message on any channel that you are following (only for Platform plans).
• [message:update](https://app.wassenger.com/help/webhooks#when-a-message-is-updated): Notified on every message update: when a poll has new votes, when a meeting event attendance is confirmed or rejected by a user or when a message is edited.
• [message:reaction](https://app.wassenger.com/help/webhooks#on-message-reactions): Notified on every new message reaction, including both message reaction addition and deletion. Works for both user and group chats. Channels are not supported.
• [status:update](https://app.wassenger.com/help/webhooks#on-message-reactions): Notified on every new user status (story) publication: status updates can have text, image or video. You can only see status updates from WhatsApp contacts.
• [chat:update](https://app.wassenger.com/help/webhooks#chat-updated): Notified on every chat update: when a chat status is assigned, unassigned, resolved, or unresolved, via API or manually by any user from the chat interface.
• [contact:update](https://app.wassenger.com/help/webhooks#contact-updated): Notified on every contact update: when contact information, metadata or status (active, blocked) is updated via API or manually by a user from the chat or CRM.

When a new inbound message is received 🔗

Event: message:in:new

This event is notified on every new incoming message sent by third-party users or group chats to your WhatsApp number.

{
  "object": "message",
  "event": "message:in:new",
  "created": 17211094,
  "device": {
    "id": "61b37a069cba0c15d",
    "phone": "+1234567890",
    "alias": "Marketing",
    "plan": "io-enterprise",
    "version": 1
  },
  "data": {
    "id": "D94B1A12EC4E83F5F4CC71EC2B1E",
    "type": "text",
    "flow": "inbound",
    "status": "active",
    "ack": "delivered",
    "from": "13245635780@c.us",
    "fromNumber": "+13245635780",
    "to": "1234567890@c.us",
    "toNumber": "+1234567890",
    "date": "2022-08-19T10:59:21.000Z",
    "timestamp": 16609067,
    "body": "Hello",
    "chat": {
      "id": "1234567890@c.us",
      "name": "Bob A.",
      "date": "2023-10-17T13:20:36.000Z",
      "type": "chat",
      "status": "pending",
      "waStatus": "removed",
      "statusUpdatedAt": "2023-10-17T14:22:17.338Z",
      "deletedAt": "2023-10-18T06:16:15.163Z",
      "firstMessageAt": "2022-08-19T10:59:08.000Z",
      "lastMessageAt": "2023-10-17T13:20:36.000Z",
      "lastOutboundMessageAt": "2023-10-17T13:20:36.000Z",
      "lastInboundMessageAt": "2023-10-17T13:20:33.000Z",
      "lastReactionAt": "2023-06-14T19:04:37.000Z",
      "lastReactionEmoji": "😀",
      "lastAutoReply": "away",
      "lastAutoReplyAt": "2023-10-13T08:24:51.000Z",
      "stats": {
        "notes": 0,
        "localMessages": 51,
        "inboundMessages": 0,
        "outboundMessages": 0
      },
      "labels": ["7", "NEW", "label"],
      "owner": {
        "agent": null,
        "assigner": null,
        "assignedAt": "2023-10-05T10:28:50.350Z",
        "autoAssignAgent": "5f71e36254800",
        "autoAssignedAt": "2024-07-16T16:51:14.439",
        "previousAgent": "5f71e36254800f5",
        "unassignedAt": null,
        "autoUnassignedAt": "2023-10-17T14:22:17.338Z"
      },
      "contact": {
        "wid": "12345678909@c.us",
        "name": "Bob A.",
        "shortName": "Bob",
        "displayName": "Bob",
        "formattedName": "Bob A.",
        "formattedShortName": "Bob",
        "syncedAt": "2024-05-11T21:26:09.145Z",
        "phone": "+12345678909",
        "image": {
          "url": "https://pps.whatsapp.net/v/t61.24694-24/411911369_3591536647785509_6334106330772289684_n.jpg?ccb=11-4&oh=01_Q5AaIEXiVwMlj4JyYkLIA8aT5uBxvocjEbbOqBC52ccmj-dF&oe=669E512A&_nc_sid=e6ed6c&_nc_cat=101"
        },
        "type": "user",
        "updatedAt": "2024-06-05T16:37:18.034Z",
        "createdBy": null,
        "locationInfo": {
          "alpha2": "US",
          "alpha3": "USA",
          "countryCallingCodes": ["+1"],
          "currencies": ["USD"],
          "emoji": "",
          "ioc": "USA",
          "languages": [
            {
              "code": "USA",
              "iso": "en",
              "name": "English",
              "nativeName": "English"
            }
          ],
          "name": "United States",
          "status": "assigned"
        },
        "metadata": [
          {
            "key": "CRM_CUSTOMER_ID",
            "value": "a1c46535"
          },
          {
            "key": "CRM_LINK",
            "value": "https://crm.company.com/customers/a1c465355"
          }
        ],
        "businessInfo": {
          "address": "350 5th Ave, New York, NY 10118",
          "description": "Company Name",
          "latitude": 40.748474043,
          "longitude": -73.98542196,
          "categories": [
            {
              "id": "1065597503",
              "name": "Software business"
            }
          ],
          "website": [],
          "businessHours": {
            "timezone": "America/New_York",
            "config": [
              {
                "weekDay": "monday",
                "mode": "open_24h"
              },
              {
                "weekDay": "tuesday",
                "mode": "specific_hours"
              },
              {
                "weekDay": "wednesday",
                "mode": "specific_hours",
                "openTime": 480,
                "closeTime": 1080
              },
              {
                "weekDay": "thursday",
                "mode": "appointment_only"
              },
              {
                "weekDay": "friday",
                "mode": "appointment_only"
              },
              {
                "weekDay": "saturday",
                "mode": "appointment_only"
              }
            ]
          },
          "options": {
            "cart": true,
            "catalog": true
          }
        }
      },
      "statusUpdatedBy": "5f71e36254800f53",
      "lastAutoReplyMessage": "3EB02C30928C59",
      "links": {
        "chat": "/v1/chat/61b37a069cba0c1/chats/12345678909@c.us"
      }
    },
    "events": {
      "sent": {
        "date": "2024-07-16T12:00:00.000Z"
      }
    },
    "meta": {
      "rtl": false,
      "containsEmoji": false,
      "isGif": false,
      "isStar": false,
      "isGroup": false,
      "isForwarded": false,
      "isEphemeral": false,
      "isNotification": false,
      "isLive": false,
      "isBroadcast": false,
      "isBizNotification": false,
      "isDoc": false,
      "isLinkPreview": false,
      "isPSA": false,
      "isRevoked": false,
      "isUnreadType": false,
      "isFailed": false,
      "source": "android",
      "autoReply": null,
      "isFirstMessage": true,
      "isChannel": false,
      "notifyName": ""
    },
    "scope": "message",
    "webhook": {
      "status": "notified",
      "webhookSyncedAt": "2022-08-23T08:40:47.371Z"
    },
    "links": {
      "message": "/v1/chat/61b37a069cba0/messages/D94B1A12EC4E83F5F4CC71EC2",
      "chat": "/v1/chat/61b37a069cba0/chats/12345678909@c.us",
      "contact": "/v1/chat/61b37a069cba0/contacts/12345678909@c.us",
      "chatMessages": "/v1/chat/61b37a069cba0c/messages?chat=12345678909@c.us",
      "device": "/v1/devices/61b37a069cba0c"
    }
  }
}

🤩 🤖 Wassenger is a complete communication platform and API solution for WhatsApp. Explore more than 100+ API use cases and automate anything on WhatsApp by signing up for a free trial and getting started in minutes!

When a new outbound message is successfully delivered 🔗

Event: message:out:new

This event is notified on every new outbound message sent from your number to any user or group chat.

Note this event will be notified for every outbound message, whether it is sent through the API, web chat and from WhatsApp mobile app or other connected linked devices from WhatsApp Desktop or WhatsApp Web.

{
  "object": "message",
  "event": "message:out:new",
  "created": 1721109401,
  "device": {
    "id": "61b37a069cba0c15d6c8",
    "phone": "+12345678909",
    "alias": "Marketing",
    "plan": "io-enterprise",
    "version": 1
  },
  "data": {
    "id": "048E55811DB6AC1B97F",
    "type": "text",
    "flow": "outbound",
    "status": "active",
    "ack": "read",
    "from": "12345678909@c.us",
    "fromNumber": "+12345678909",
    "to": "13245635780@c.us",
    "toNumber": "+13245635780",
    "date": "2022-08-19T10:59:08.000Z",
    "timestamp": 1660906748,
    "body": "Hello there!",
    "chat": {
      "id": "1235475685@c.us",
      "name": "Bob A.",
      "date": "2023-10-17T13:20:36.000Z",
      "type": "chat",
      "status": "pending",
      "waStatus": "removed",
      "statusUpdatedAt": "2023-10-17T14:22:17.338Z",
      "deletedAt": "2023-10-18T06:16:15.163Z",
      "firstMessageAt": "2022-08-19T10:59:08.000Z",
      "lastMessageAt": "2023-10-17T13:20:36.000Z",
      "lastOutboundMessageAt": "2023-10-17T13:20:36.000Z",
      "lastInboundMessageAt": "2023-10-17T13:20:33.000Z",
      "lastReactionAt": "2023-06-14T19:04:37.000Z",
      "lastReactionEmoji": "😀",
      "lastAutoReply": "away",
      "lastAutoReplyAt": "2023-10-13T08:24:51.000Z",
      "stats": {
        "notes": 0,
        "localMessages": 51,
        "inboundMessages": 0,
        "outboundMessages": 0
      },
      "labels": ["7", "NEW", "label"],
      "owner": {
        "agent": null,
        "assigner": null,
        "assignedAt": "2023-10-05T10:28:50.350Z",
        "autoAssignAgent": "5f71e36254800f533ab79148",
        "autoAssignedAt": "2024-07-16T16:51:14.439",
        "previousAgent": "5f71e36254800f533ab79148",
        "unassignedAt": null,
        "autoUnassignedAt": "2023-10-17T14:22:17.338Z"
      },
      "contact": {
        "wid": "13245635780@c.us",
        "name": "Bob A.",
        "shortName": "Bob",
        "displayName": "Bob",
        "formattedName": "Bob A.",
        "formattedShortName": "Bob",
        "syncedAt": "2024-05-11T21:26:09.145Z",
        "phone": "+13245635780",
        "image": {
          "url": "https://pps.whatsapp.net/v/t61.24694-24/411911369_3591536647785509_6334106330772289684_n.jpg?ccb=11-4&oh=01_Q5AaIEXiVwMlj4JyYkLIA8aT5uBxvocjEbbOqBC52ccmj-dF&oe=669E512A&_nc_sid=e6ed6c&_nc_cat=101"
        },
        "type": "user",
        "updatedAt": "2024-06-05T16:37:18.034Z",
        "createdBy": null,
        "locationInfo": {
          "alpha2": "US",
          "alpha3": "USA",
          "countryCallingCodes": ["+1"],
          "currencies": ["USD"],
          "emoji": "",
          "ioc": "USA",
          "languages": [
            {
              "code": "ENG",
              "iso": "en",
              "name": "English",
              "nativeName": "English"
            }
          ],
          "name": "United States",
          "status": "assigned"
        },
        "metadata": [
          {
            "key": "CRM_CUSTOMER_ID",
            "value": "a1c46535"
          },
          {
            "key": "CRM_LINK",
            "value": "https://crm.company.com/customers/a1c465355"
          }
        ]
      },
      "statusUpdatedBy": "5f71e36254800f533ab791",
      "lastAutoReplyMessage": "3EB02C30928C59CBB4A",
      "links": {
        "chat": "/v1/chat/61b37a069cba0c15d6c89757/chats/1235475685@c.us"
      }
    },
    "events": {
      "sent": {
        "date": "2022-08-23T08:40:45.519Z"
      }
    },
    "meta": {
      "rtl": false,
      "containsEmoji": false,
      "isGif": false,
      "isStar": false,
      "isGroup": false,
      "isForwarded": false,
      "isEphemeral": false,
      "isNotification": false,
      "isLive": false,
      "isBroadcast": false,
      "isBizNotification": false,
      "isDoc": false,
      "isLinkPreview": false,
      "isPSA": false,
      "isRevoked": false,
      "isUnreadType": false,
      "isFailed": false,
      "source": "android",
      "autoReply": null,
      "isFirstMessage": true,
      "isChannel": false,
      "notifyName": "",
      "via": "remote"
    },
    "scope": "message",
    "webhook": {
      "status": "pending",
      "webhookSyncedAt": null
    },
    "links": {
      "message": "/v1/chat/61b37a069cba0c15d6c8/messages/048E55811DB6AC1B97FC8614C2F",
      "messageAckinfo": "/v1/chat/61b37a069cba0c15d6c8/messages/048E55811DB6AC1B97FC8614C2F/ackinfo",
      "chat": "/v1/chat/61b37a069cba0c15d6c8/chats/13245635780@c.us",
      "contact": "/v1/chat/61b37a069cba0c15d6c8/contacts/13245635780@c.us",
      "chatMessages": "/v1/chat/61b37a069cba0c15d6c8/messages?chat=13245635780@c.us",
      "device": "/v1/devices/61b37a069cba0c15d6c8"
    }
  }
}

🤩 🤖 Wassenger is a complete communication platform and API solution for WhatsApp. Explore more than 100+ API use cases and automate anything on WhatsApp by signing up for a free trial and getting started in minutes!

When a sent message is read or played by the user 🔗

Event: message:out:ack

This event is notified when a sent message is read or played (for audio messages only) by the receiver user.

Note: this event is only available in the Business and Enterprise plans.

{
  "object": "message",
  "event": "message:out:ack",
  "created": 1721109401,
  "ack": "read",
  "device": {
    "id": "61b37a069cba0c15d6c",
    "phone": "+12345678909",
    "alias": "Marketing",
    "plan": "io-enterprise",
    "version": 1
  },
  "data": {
    "id": "048E55811DB6AC1B97FC8614C2FF90EB",
    "type": "text",
    "flow": "outbound",
    "status": "active",
    "ack": "read",
    "from": "12345678909@c.us",
    "fromNumber": "+12345678909",
    "to": "12345678901@c.us",
    "toNumber": "+12345678909",
    "date": "2022-08-19T10:59:08.000Z",
    "timestamp": 1660906748,
    "body": "Hello There!",
    "chat": {
      "id": "12345678909@c.us",
      "name": "Bob A.",
      "date": "2023-10-17T13:20:36.000Z",
      "type": "chat",
      "status": "pending",
      "waStatus": "removed",
      "statusUpdatedAt": "2023-10-17T14:22:17.338Z",
      "deletedAt": "2023-10-18T06:16:15.163Z",
      "firstMessageAt": "2022-08-19T10:59:08.000Z",
      "lastMessageAt": "2023-10-17T13:20:36.000Z",
      "lastOutboundMessageAt": "2023-10-17T13:20:36.000Z",
      "lastInboundMessageAt": "2023-10-17T13:20:33.000Z",
      "lastReactionAt": "2023-06-14T19:04:37.000Z",
      "lastReactionEmoji": "😀",
      "lastAutoReply": "away",
      "lastAutoReplyAt": "2023-10-13T08:24:51.000Z",
      "stats": {
        "notes": 0,
        "localMessages": 51,
        "inboundMessages": 0,
        "outboundMessages": 0
      },
      "labels": ["7", "NEW", "label"],
      "owner": {
        "agent": null,
        "assigner": null,
        "assignedAt": "2023-10-05T10:28:50.350Z",
        "autoAssignAgent": "5f71e36254800f533ab",
        "autoAssignedAt": "2024-07-16T16:51:14.439",
        "previousAgent": "5f71e36254800f533ab",
        "unassignedAt": null,
        "autoUnassignedAt": "2023-10-17T14:22:17.338Z"
      },
      "contact": {
        "wid": "12345678909@c.us",
        "name": "Bob A.",
        "shortName": "Bob",
        "displayName": "Bob",
        "formattedName": "Bob A.",
        "formattedShortName": "Bob",
        "syncedAt": "2024-05-11T21:26:09.145Z",
        "phone": "+12345678909",
        "image": {
          "url": "https://pps.whatsapp.net/v/t61.24694-24/411911369_3591536647785509_6334106330772289684_n.jpg?ccb=11-4&oh=01_Q5AaIEXiVwMlj4JyYkLIA8aT5uBxvocjEbbOqBC52ccmj-dF&oe=669E512A&_nc_sid=e6ed6c&_nc_cat=101"
        },
        "type": "user",
        "updatedAt": "2024-06-05T16:37:18.034Z",
        "createdBy": null,
        "locationInfo": {
          "alpha2": "US",
          "alpha3": "USA",
          "countryCallingCodes": ["+1"],
          "currencies": ["USD"],
          "emoji": "",
          "ioc": "USA",
          "languages": [
            {
              "code": "ENG",
              "iso": "en",
              "name": "English",
              "nativeName": "English"
            }
          ],
          "name": "United States",
          "status": "assigned"
        },
        "metadata": [
          {
            "key": "CRM_CUSTOMER_ID",
            "value": "a1c465355"
          },
          {
            "key": "CRM_LINK",
            "value": "https://crm.company.com/customers/a1c465355"
          }
        ]
      },
      "statusUpdatedBy": "5f71e36254800f533ab",
      "lastAutoReplyMessage": "3EB02C30928C59CBB",
      "links": {
        "chat": "/v1/chat/61b37a069cba0c15d6/chats/12345678909@c.us"
      }
    },
    "events": {
      "sent": {
        "date": "2022-08-23T08:40:45.519Z"
      }
    },
    "meta": {
      "rtl": false,
      "containsEmoji": false,
      "isGif": false,
      "isStar": false,
      "isGroup": false,
      "isForwarded": false,
      "isEphemeral": false,
      "isNotification": false,
      "isLive": false,
      "isBroadcast": false,
      "isBizNotification": false,
      "isDoc": false,
      "isLinkPreview": false,
      "isPSA": false,
      "isRevoked": false,
      "isUnreadType": false,
      "isFailed": false,
      "source": "android",
      "autoReply": null,
      "isFirstMessage": true,
      "isChannel": false,
      "notifyName": "",
      "via": "remote"
    },
    "scope": "message",
    "webhook": {
      "status": "pending",
      "webhookSyncedAt": null
    },
    "links": {
      "message": "/v1/chat/61b37a069cba0c15d6c/messages/048E55811DB6AC1B97FC8614C",
      "messageAckinfo": "/v1/chat/61b37a069cba0c15d6c/messages/048E55811DB6AC1B97FC8614C/ackinfo",
      "chat": "/v1/chat/61b37a069cba0c15d6c/chats/12345678909@c.us",
      "contact": "/v1/chat/61b37a069cba0c15d6c/contacts/12345678909@c.us",
      "chatMessages": "/v1/chat/61b37a069cba0c15d6c/messages?chat=12345678909@c.us",
      "device": "/v1/devices/61b37a069cba0c15d6c"
    }
  }
}

🤩 🤖 Wassenger is a complete communication platform and API solution for WhatsApp. Explore more than 100+ API use cases and automate anything on WhatsApp by signing up for a free trial and getting started in minutes!

When a message delivery fails 🔗

Event: message:out:failed

This event is notified when outbound messages fail to be delivered due to the target number not being found, invalid or expired media content or maximum retries exceeded.

This event uses JSON payload data that is structured as an array of objects, thus multiple messages can be notified in the same HTTP POST request, up to 25 items per notification.

[
  {
    "event": "message:out:failed",
    "date": "2018-12-08T15:01:48.518Z",
    "entity": "message",
    "entityId": "5bf612faa893b00016",
    "entityUrl": "https://api.wassenger.com/v1/messages/5bf612faa893b00016",
    "user": "5bd75ab235623e00162",
    "data": {
      "id": "5bf612faa893b00016c",
      "phone": "+12345678909",
      "status": "failed",
      "deliveryStatus": "failed",
      "createdAt": "2022-11-22T02:22:50.955Z",
      "sentAt": "2022-11-22T02:29:29.254Z",
      "failedAt": null,
      "processedAt": "2022-11-22T02:28:54.818Z",
      "webhookStatus": "pending",
      "message": "This is an automated message sent from the API",
      "priority": "normal",
      "schedule": {
        "enabled": false
      },
      "retry": {
        "count": 1,
        "lastRetryAt": "2022-11-22T02:25:58.414Z"
      },
      "device": {
        "id": "3bf5d1ff2ff2bd00169",
        "phone": "+12345678909",
        "alias": "My WA Delivery Device",
        "description": "Device 1 for customer support and product notifications",
        "status": "verified",
        "session": {
          "status": "online",
          "error": false,
          "lastSyncAt": "2022-12-02T10:11:16.008Z"
        },
        "createdAt": "2022-11-20T09:21:03.898Z",
        "queue": {
          "total": 100,
          "size": 0,
          "available": 100
        },
        "profile": {
          "name": "+12345678909",
          "info": null,
          "lastSyncAt": "2022-11-22T22:14:33.334Z",
          "imagePath": "/v1/devices/3bf5d1ff2ff2bd00/profile/image"
        },
        "links": {
          "device": {
            "method": "GET",
            "url": "https://api.wassenger.com/v1/devices/3bf5d1ff2ff2bd00169"
          },
          "scan": {
            "method": "GET",
            "url": "https://api.wassenger.com/v1/devices/3bf5d1ff2ff2bd00169/scan"
          },
          "sync": {
            "method": "GET",
            "url": "https://api.wassenger.com/v1/devices/3bf5d1ff2ff2bd00169/sync"
          },
          "health": {
            "method": "GET",
            "url": "https://api.wassenger.com/v1/devices/3bf5d1ff2ff2bd00169/health"
          },
          "profileImage": {
            "method": "GET",
            "url": "https://api.wassenger.com/v1/devices/3bf5d1ff2ff2bd00169/profile/image"
          },
          "messages": {
            "method": "GET",
            "url": "https://api.wassenger.com/v1/messages?devices=3bf5d1ff2ff2bd00169"
          }
        },
        "stats": {
          "total": {
            "sent": 565,
            "failed": 103,
            "media": 0,
            "totalUpstreamSize": 0,
            "totalDeliveryTime": 13331,
            "totalUpstreamSpeed": 0
          },
          "minutes": {
            "sent": 4,
            "failed": 0,
            "media": 0,
            "totalUpstreamSize": 0,
            "totalDeliveryTime": 48,
            "totalUpstreamSpeed": 0
          },
          "quarter": {
            "sent": 4,
            "failed": 0,
            "media": 0,
            "totalUpstreamSize": 0,
            "totalDeliveryTime": 48,
            "totalUpstreamSpeed": 0
          },
          "hour": {
            "sent": 10,
            "failed": 1,
            "media": 0,
            "totalUpstreamSize": 0,
            "totalDeliveryTime": 114,
            "totalUpstreamSpeed": 0
          },
          "day": {
            "sent": 10,
            "failed": 1,
            "media": 0,
            "totalUpstreamSize": 0,
            "totalDeliveryTime": 114,
            "totalUpstreamSpeed": 0
          },
          "week": {
            "sent": 10,
            "failed": 1,
            "media": 0,
            "totalUpstreamSize": 0,
            "totalDeliveryTime": 114,
            "totalUpstreamSpeed": 0
          },
          "month": {
            "sent": 565,
            "failed": 103,
            "media": 0,
            "totalUpstreamSize": 0,
            "totalDeliveryTime": 13331,
            "totalUpstreamSpeed": 0
          },
          "year": {
            "sent": 565,
            "failed": 103,
            "media": 0,
            "totalUpstreamSize": 0,
            "totalDeliveryTime": 13331,
            "totalUpstreamSpeed": 0
          }
        }
      }
    }
  }
]

FAQ

Can I use the API to create and manage webhooks?

Of course, you can. Please check the API documentation for more details.

Can I use a local server for development and testing?

Yes, you can. To allow Wassenger to communicate with your local development server from the Internet, you need to create a tunnel.

There are multiple solutions out there, but a popular, free one is Ngrok.

Find below a tutorial about how to use Ngrok:

• Expose your local server to the Internet using Ngrok

Can I use a free webhook service for testing?

Yes, we recommend using Pipedream's free service for webhooks testing and debugging.

• Webhook Free Service for Testing & Debugging

Can I use webhooks with Zapier or Make integration hubs?

Yes, you can! Zapier and Make (formerly Integromat) works great with webhooks.

Here are some useful tutorials to get started:

• How to use Webhooks with Make.com
• How to use Webhooks with Zapier

When a webhook event notification is considered successful or failed?

Your webhook consumer server must process the HTTP request and reply with a successful status code (2xx).

• ✅ A notification is successful when your server replies with a 2xx HTTP status code (200-299). The response body can be empty, for example with a 204 status code.
• ✅ Reply within 30 seconds. Depending on the event, the system stops waiting after 30 or 45 seconds and counts the attempt as failed.
• ✅ Any other status code counts as a failed attempt, including 4xx and 5xx codes.
• ✅ Redirects (3xx) are not followed and count as a failed attempt, so register the final URL of your endpoint. Some events are sent with a trailing slash added to a URL that has no query string (https://example.com/hook is called as https://example.com/hook/), so make sure your server answers that path without redirecting.
• ✅ A connection that cannot be established, for example because the domain does not resolve or the connection is refused, counts as a failed attempt.
• ✅ Which failed notifications are retried, and when a webhook that keeps failing is disabled, is explained below in "What happens in case of notification failure?" and "When is a webhook disabled?".

What is the webhook notification timeout?

Our system will make an HTTP request to the remote endpoint URL you provide every time a new message/device event happens.

Information will be encoded in JSON format as part of the HTTP body data.

Your server must accept and read the body of the HTTP POST request and process it accordingly.

Your server should reply with a 2xx HTTP status code (200-299) within 30 seconds. Otherwise, the notification counts as failed; see below for which events are retried and how.

How data will be sent to my server?

The system sends HTTP(S) POST requests with a JSON-encoded body (Content-Type = application/json)

How to implement a webhooks server?

This depends on the technology/programming language you use, but there are plenty of options here.

You simply need an HTTP(S) server running accessible from the Internet that can handle HTTP POST incoming requests.

Take a look at these resources for additional information:

• Introduction to Webhooks 📈
• Another introduction to Webhooks 🔗
• Webhook Free Service for Testing & Debugging 🧪
• Expose your local server to the Internet using Ngrok 🖥️
• Handling Webhook Requests in PHP 💻
• Webhook server in Go 🧑‍💻

Is there a webhook events limit?

No, there is no limit. Typically, there is one webhook event notified per received or sent WhatsApp message.

You can receive messages with no limit. The system will notify your webhook endpoint of up to 5 messages per second.

If you receive messages faster than that, the system will queue them and notify them as soon as possible.

Note that media messages take a bit longer to be processed than text messages due to file content downloading and storage.

What’s the webhook event delivery speed?

On average, you can expect to receive a webhook event per WhatsApp number with a delay of 500-1000 milliseconds since the time the message was received on your WhatsApp number, plus the time your system can process the webhook event.

Note this applies to text messages. For multimedia messages, the message processing would take a bit longer due to file downloading and storage, from 1 extra second up to 10 seconds, depending on the size of the media file received.

How to secure a webhook server?

First, we strongly recommend using HTTPS (HTTP + TLS encryption) on your server.

Secondly, you can use a custom URL query param with a secret key that is private.

Example: [https://mycompany.com/webhooks?key=some-secret-token-here](https://mycompany.com/webhooks?key=some-secret-token-here)

How many JSON objects are included per HTTP request body?

This depends on the webhook event notified to your server.

For the following webhook events, the JSON payload sent to your server is a single object, not an array:

• message:in:new
• message:out:new
• message:out:ack

For the following webhook events, a maximum of 20 objects can be sent per HTTP POST request:

• message:out:failed
• message:out:sent: legacy event, only available in Gateway plans

🤩 🤖 Wassenger is a complete API solution for WhatsApp. Sign up for a 7-day free trial and get started in minutes!

What happens in case of notification failure?

The failed notifications below are retried, depending on the event and on the type of WhatsApp number. Events not listed here may not be retried.

• message:in:new and message:out:ack on QR numbers: the event stays pending and is sent again on each pass, every one to two minutes, until it is delivered or the message is 7 days old (5 days for read receipts).
• message:out:failed (and the legacy message:out:sent of Gateway plans) for messages sent through the API on QR numbers: retried after 30 seconds, then waiting twice as long each time, up to 15 minutes between retries, until it is delivered or 7 days have passed since the message was sent or failed.
• Message events on WhatsApp Business API numbers, including Coexistence numbers: each delivery makes up to 4 attempts, 3 seconds apart (only one if your server answers with a 3xx or 4xx code, its domain does not resolve or the connection is refused). If they all fail, the event is retried up to 25 more times: first after 7.5 seconds, then waiting 1.5 times longer each time, up to 10 minutes between retries. About 2 hours and 40 minutes after the first failure, the event is dropped.
• number:session, chat:update and contact:update: up to 4 attempts, a few seconds apart (only one if your server answers with a 3xx or 4xx code, its domain does not resolve or the connection is refused). If they all fail, the event is dropped.

For the message events above, a 4xx response is retried like any other failure: it only cuts the quick attempts short. The same event can reach your server more than once, for example when your server processed it but replied too late, so make sure your server can handle duplicates.

When is a webhook disabled?

Failed deliveries are counted per webhook. The count goes up at most once every 2 minutes, by the number of failures reported at that moment. That is usually one, so reaching 60 takes about 2 hours of continuous failures. A busy QR number is different: it can report up to 35 failures at once, so its webhook can be disabled after only a few minutes of failures. On QR numbers, a connection that is refused or reset is retried but not counted, so it never disables the webhook.

• ✅ When the count reaches 11, you receive a "Webhook is failing" email with the latest logs, at most once every 30 minutes.
• ✅ When it reaches 60, the webhook is disabled and you receive a "Webhook was permanently disabled" email. If the webhook was already disabled within the previous hour (for example, you enabled it again and it kept failing), it is disabled at 120 instead, without a new email. A disabled webhook receives no events.
• ✅ A single successful delivery resets the count to 0.
• ✅ Once the problem is fixed, enable the webhook again from the webhooks section of the web app or with the API: POST /v1/webhooks/{webhookId}/enable. Enabling it also resets the count to 0.

🤩 🤖 Wassenger is a complete communication platform and API solution for WhatsApp. Explore more than 100+ API use cases and automate anything on WhatsApp by signing up for a free trial and getting started in minutes!