Webhooks

Webhooks

Webhooks are user-defined HTTP callbacks that are triggered by specific events. Whenever that trigger event occurs, the WhatsApp Business API client sees the event, collects the data, and immediately sends a notification (HTTP request) to the Webhook URL specified in the application settings updating the status of sent messages or indicating when you receive a message.

It is important that your Webhook returns an HTTPS 2xx OK response to notifications. Otherwise the WhatsApp Business API client considers that notification as failed and tries again after a delay.

Retrying failed webhooks

When the app to which we’re sending the webhook fails to send a response with a 2xx status code the package will consider the call as failed. The call will also be considered failed if the remote app doesn’t respond within 3 seconds. When a webhook call fails, we’ll retry the call two more times.

To not hammer the remote app we’ll wait some time between each attempt. By default, we wait 10 seconds between the first and second attempt, 100 seconds between the third and the fourth, 1000 between the fourth and the fifth and so on. The maximum amount of seconds that we’ll wait is 100 000, which is about 27 hours.

Signature

If you wish to have your callbacks signed and have made the proper configuration for this, the callbacks will have the following signature-related headers.

Name Description
Signature The signature generated by system with webhook id as secret

Examples

Message Status Notification

{
  "event": "whatsapp:message:status",
  "payload": {
    "id": "a418d672-9781-4d97-b517-a56f7d95ad8a",
    "channel": "whatsapp",
    "from": "919019120120",
    "to": "9190199xxxxx",
    "status": "sent|delivered|read|failed|deleted",
    "delivered_at": "2021-06-18T14:48:06.886358Z",
    "read_at": "2021-06-18T14:48:06.886358Z",
    "processed_at": "2021-06-18T14:48:06.886358Z",
    "timestamp": "2021-06-18T14:48:06.886358Z",
    "foreign_id": "your-business-identifier"
  }
}

Message Incoming Notification

{
  "event": "whatsapp:message:in",
  "payload": {
    "id": "our-message-id",
    "channels": [
      {
        "name": "whatsapp",
        "to": "919019120120"
      }
    ],
    "recipient": {
      "from": "91XXXXXX",
      "user": {
        "id": "unique-user-id",
        "username": "username",
        "first_name": "user first name",
        "last_name": "user last name",
        "email": null,
        "phone": "user phone number",
        "user_info": {
          "picture": "url-of-profile-picture",
          "gender": null,
          "title": "user status or designation"
        }
      }
    },
    "message": {
      "type": "text",
      "payload": {
        "text": "This is a simple text message from whatsapp channel"
      }
    }
  }
}

Incoming Media

{
  "event": "whatsapp:message:in",
  "payload": {
    "id": "our-message-id",
    "channels": [
      {
        "name": "whatsapp",
        "to": "919019120120"
      }
    ],
    "recipient": {
      "from": "91XXXXXX",
      "user": {
        "id": "unique-user-id",
        "username": "username",
        "first_name": "user first name",
        "last_name": "user last name",
        "email": null,
        "phone": "user phone number",
        "user_info": {
          "picture": "url-of-profile-picture",
          "gender": null,
          "title": "user status or designation"
        }
      }
    },
    "message": {
      "type": "image",
      "payload": {
        "url": "https://domin-name.com/your_image_path.png",
        "caption": "some caption for image",
        "filename": ""
      }
    }
  }
}