1. Home
  2. v2
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, click here to create webhook.

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.

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.

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 
{
  "event": "whatsapp:message:status",
  "payload": {
    "id": "a418d672-9781-4d97-b517-a56f7d95ad8a",
    "channel": "whatsapp",
    "from": "919019120xxx",
    "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",
    "foreign_id": "your-business-identifier",
    "timestamp": "2021-06-18T14:48:06.886358Z"
  }
}

{
  "event": "whatsapp:message:in",
  "payload": {
    "id": "our-message-id",
    "channels": [
      {
        "name": "whatsapp",
        "to": "919019120xxx"
      }
    ],
    "recipient": {
      "from": "91XXXXXX",
      "user": {
        "id": "unique-id",
        "identifier_id": "unique-identifier-id",
        "subscriber_id": "unique-subscriber-id",
        "identity": "unique-user-identity",
        "username": "username",
        "first_name": "user first name",
        "middle_name": "user middle name",
        "last_name": "user last name",
        "email": "user email",
        "phone": "user phone number",
        "attributes": "user attributes",
        "user_info": {
          "picture": "null",
          "gender": "user-gender",
          "title": "null"
        }
      }
    },
    "message": {
      "type": "text",
      "payload": {
        "text": "This is a simple text message from whatsapp channel"
      },
      "id": "b215da80-04bf-46f8-9b21-674c359b94b3",
      "timestamp": "2024-07-09T10:03:37.338022Z"
    }
  }
}

{
  "event": "whatsapp:message:in",
  "payload": {
    "id": "our-message-id",
    "channels": [
      {
        "name": "whatsapp",
        "to": "919019120xxx"
      }
    ],
    "recipient": {
      "from": "91XXXXXX",
      "user": {
        "id": "unique-id",
        "identifier_id": "unique-identifier-id",
        "subscriber_id": "unique-subscriber-id",
        "identity": "unique-user-identity",
        "username": "username",
        "first_name": "user first name",
        "middle_name": "user middle name",
        "last_name": "user last name",
        "email": "user email",
        "phone": "user phone number",
        "attributes": "user attributes",
        "user_info": {
          "picture": "null",
          "gender": "user-gender",
          "title": "null"
        }
      }
    },
    "message": {
      "type": "image",
      "payload": {
        "url": "https://domin-name.com/your_image_path.png",
        "caption": "some caption for image",
        "filename": ""
      },
      "id": "b215da80-04bf-46f8-9b21-674c359b94b3",
      "timestamp": "2024-07-09T10:03:37.338022Z"
    }
  }
}

For users seeking enhanced customization, compose webhook will help to receive the customized webhook payload to precisely match your preferences and requirements.

  • Navigate to the Webhooks section and click on the Compose Webhook.
  • Give the identification name.
  • To set up the Compose Webhook, you need to provide a callback URL. This URL is where the composed payload will be sent.
  • In the url you can pass the replaced variables.
  https://www.domain.com/ack/receive?id={{id}}&mobile={{payload.mobile}}&status={{payload.status}}  

  https://www.domain.com/ack/receive?message_id={{payload.id}}&mobile_number={{payload.mobile}}&message_status={{payload.status}}
  • HTTP Method: Specify the HTTP method for the webhook request, such as GET, POST or PUT.
  • Headers: Define custom headers if needed, like Authorization headers or custom headers.
  • Body Format: Choose between JSON or FormData for the payload.
  • Upon creation, you will receive an id for the newly created Webhook.
  • To request delivery reports, include the webhook_id parameter and its corresponding value in your API Request. Once the request is made, you will receive the delivery report as you configured.
  • here keys you can give any name but value should be availebe in the below replaced variables Ex: {{payload.mobile}}.
  curl -X POST \
  https://www.domain.com/ack/receive?id={{payload.id}} \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer %token%", \
  -d '{
      "id": "{{payload.id}}",
      "mobile": "{{payload.mobile}}",
      "message_status": "{{payload.status}}",
      "read_at": "{{payload.read_at}}"
    }'

Replaced variables can be used while creating or composing a webhook

Name Description
id Message Id generated by us
from Whtsapp business number
to Mobile number with country code
status sent|delivered|read|failed|deleted
delivered_at Delivered to handset time
read_at user message read time
processed_at Processed time
submit_time Sent to operator time
foreign_id your-business-identifier
Table of Contents