Inbound Events Webhook

📄 Contents
What are inbound events
Listening to inbound events
Inbound Event Object Structure
HMAC Validation

What are inbound events

WhatsApp platform operates in an asynchronous manner. For example when you send a message, WhatsApp cloud APIs accept the request and then publish events indication wether the message was sent or not. They also publish events when a message is delivered, read, etc... Inbound messages to your WhatsApp number are also published as events.

Listening to inbound events

There are 2 types of inbound event webhooks you can configure

Pass through events webhook - Meta events in Meta format passed directly to you

Chakra webhook - Select events passed in a friendlier format

Pass Through Events Webhook

This webhook allows you to receive all incoming events from Meta directly. This inludes inbound messages, status events, message template updates, account updates, etc...

How to configure

Visit the WhatsApp Setup page

Click the More tab

Locate the "pass-thorugh webhook url for Meta events" field (see screesnshot below)

Enter your webhook url in the above field

Click Save from the top right cornder of the oate

The format of these events the same as described in meta documentation. You can read more about these events and types from Meta's official documentation here

Sample Inbound text message event

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "83784929738012",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "917259775805",
              "phone_number_id": "694794789348887"
            },
            "contacts": [
              {
                "profile": {
                  "name": "John"
                },
                "wa_id": "919911223344"
              }
            ],
            "messages": [
              {
                "from": "919911223344",
                "id": "wamid.HBgMOTEST3AxMjU4NDMzFQIAEhgUM0VCMDM3RjlEQTNDQTBEMjQ2Q275",
                "timestamp": "1756322278",
                "text": {
                  "body": "Hi, can you please help me out with an issue"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Sample Inbound image message event

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "83784929738012",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "917259775805",
              "phone_number_id": "694794789348887"
            },
            "contacts": [
              {
                "profile": {
                  "name": "John"
                },
                "wa_id": "919911223344"
              }
            ],
            "messages": [
              {
                "from": "919911223344",
                "id": "wamid.HBgMOTEST3AxMjU4NDMzFQIAEhgUM0VCMDM3RjlEQTNDQTBEMjQ2Q275",
                "timestamp": "1756322278",
                "type":"image",
                "image":  {
                  "mime_type": "image/jpeg",
                  "sha256": "t8K9fuzwAoeBSOoIZWkBlI1hTflUHqSwCvGwJ+exm74=",
                  "id": "1402363984735353"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

sample message_template_sends event

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "83784929738012",
      "changes": [
        {
          "field": "message_template_sends",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "916363180853",
              "phone_number_id": "694794789348887"
            },
            "message_template_sends": [
              {
                "id": "wamid.HBgMOTE5OTAxMjU4NDMzFQIAERgSMjNBQkQ5NDA5NTFEN0MzOTU2AA==",
                "timestamp": 1763821065,
                "messaging_product": "whatsapp",
                "to": "919911223344",
                "type": "template",
                "template": {
                  "language": {
                    "policy": "deterministic",
                    "code": "en_US"
                  },
                  "name": "new_year_promo_24",
                  "components": [
                    {
                      "type": "body",
                      "parameters": [
                        {
                          "type": "text",
                          "text": "John"
                        }
                      ]
                    },
                    {
                      "type": "header",
                      "parameters": [
                        {
                          "type": "image",
                          "image": {
                            "link": "https://chakra-public-media.chakrahq.com/247f7fe2-bf3f-4a8e-b2e3-a60a58de321f/2025-11-22/0d242d59-eaae-4a96-833b-6b34716f0e75/novsamplephoto2.jpg"
                          }
                        }
                      ]
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Chakra Events Webhook

You can listen to these inbound events by configuring a webhook with us. The webhook configuration can be found in the 'WhatsApp Setup' plugin. Look for the input box titled "Webhook url to receive status events of API generated messages"

Provide the url to your webhook in this box and save the plugin. Please ensure that the webhook is accessible on the internet and requires no authentication.

how to configure

Visit the WhatsApp Setup page

Click the More tab

Enable the "Enable Chakra Webhooks" toggle

Locate the "Chakra webhook url" field (see screesnshot below)

Enter your webhook url in the above field

Click one or more events under "Which events to send" - The clicked event types are the events that will be sent on the webhook

Click Save from the top right cornder of the oate

Inbound Event Object Structure

There are 2 types of inbound events

deliveryStatus - These events carry the delivery status of messages that were sent earlier via API

message - These events carry inbound messages received on your phone number

Each event will have 2 keys

event - 'message' | 'status' | 'message_echo' | 'smb_message_echo'

payload - DeliverySatusPayload | MessagePayload

HMAC Validation

ChakraHQ utilizes HMAC-SHA256 to ensure the security and integrity of incoming webhook events from the WhatsApp Business Platform. This mechanism allows you to verify that the webhook events (messages, status updates, errors) actually originated from ChakraHQ and have not been tampered with.

Step 1

Set an HMAC secret for your team by going to Admin >> Team >> Secrets.

Once this is set, you will start seeing a new header 'X-Chakra-Signature-256' in the webhook events.

Step 2

To validate the request at your end - Generate an HMAC-SHA256 hash using the raw body string as the message input and your app secret as the secret key. Compare your generated hash to the hash assigned to the X-Chakra-Signature-256 header.
If the hashes match, the payload is valid. Capture the payload and digest its contents according to business needs. If they do not match, consider the payload invalid.

Important notes on generating your HMAC-SHA256 hash:

Use the raw body string as the message input. Sometimes, depending on your http framework, the raw body string might be converted to JSON or object format - which cannot be used as these formats do not return the same original value when converted back to string.

Use the HMAC-SHA256 format to compute the hash.

The value in the X-Chakra-Signature-256 header will NOT have a "sha256=" prefix.

📄 Contents#

What are inbound events#

Listening to inbound events#

Pass Through Events Webhook#

How to configure#

Sample Inbound text message event#

Sample Inbound image message event#

sample message_template_sends event#

Chakra Events Webhook#

how to configure#

Inbound Event Object Structure#

HMAC Validation#

Step 1#

Step 2#

📄 Contents