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

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:

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 (200–209).

The following conditions apply to determine

✅ HTTP response status code must be 200–209 to be successful.
✅ The webhook server must provide a valid response within 30 seconds.
✅ The webhook server can provide an empty response (204) as long as the response status code.
✅ If the response status code is not valid, the request will be retried after 15 seconds.
✅ If the response takes more than 30 seconds, the request will be retried after 15 seconds.
✅ If the same webhook event notification fails after 100 retries, it will be flagged as permanently failed.
✅ In case there are many notification failures in a row to your webhook, the system will alert you via email.

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 200–209 HTTP status code. Otherwise, it will be considered as a failed notification and it will be retried.

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 25 objects can be sent per HTTP POST request:

message:out:failed

🤩 🤖 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 system will retry the request several times, up to 50 times per webhook event, using an incremental backoff strategy.

In case of 10+ failures in a row, we will notify via email you about a potential issue in your webhook integration.

In case of persistent failures over an hour (60+ failed requests in a row), the system will disable the webhook endpoint and will notify you via email about this incident for manual intervention.

You can later re-enable the webhook once the integration issue is fixed on your end.

🤩 🤖 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!