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",
                "user_id": "IN.2363307770826624"
              }
            ],
            "messages": [
              {
                "from": "919911223344",
                "from_user_id": "IN.2363307770826624",
                "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",
                "user_id": "IN.2363307770826624"
              }
            ],
            "messages": [
              {
                "from": "919911223344",
                "from_user_id": "IN.2363307770826624",
                "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"
                          }
                        }
                      ]
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

List of supported webhook fields/events

account_alerts

The account_alerts webhook notifies you of changes to a business phone number’s messaging limit, business profile, and Official Business Account status.

account_review_update

The account_review_update webhook notifies you when a WhatsApp Business Account has been reviewed against our policy guidelines.

account_update

The account_update webhook notifies of changes to a WhatsApp Business Account’s partner-led business verification submission, its authentication-international rate eligibility, or primary business location, when it is shared with a Solution Partner, policy or terms violations, offboarding, reconnection, or when it is deleted.

automatic_events

The automatic_events webhook notifies you when we detect a purchase or lead event in a chat thread between you and a WhatsApp user who has messaged you via your Click to WhatsApp ad, if you have opted-in to Automatic Events reporting.

business_capability_update

The business_capability_update webhook notifies you of WhatsApp Business Account or business portfolio capability changes (messaging limits, phone number limits, etc.).

calls

The calls webhook notifies you of call events for user-initiated calls and business-initiated calls, such as when a call is connected or terminated.

history

The history webhook is used to synchronize the WhatsApp Business app chat history of a business customer onboarded by a solution provider.

message_template_components_update

The message_template_components_update webhook notifies you of changes to a template’s components.

message_template_quality_update

The message_template_quality_update webhook notifies you of changes to a template’s quality score.

message_template_status_update

The message_template_status_update webhook notifies you of changes to the status of an existing template.

messages

The messages webhook describes messages sent from a WhatsApp user to a business and the status of messages sent by a business to a WhatsApp user.

partner_solutions

The partner_solutions webhook describes changes to the status of a Multi-Partner Solution.

payment_configuration_update

The payment_configuration_update webhook notifies you of changes to payment configurations for Payments API India and Payments API Brazil.

phone_number_name_update

The phone_number_name_update webhook notifies you of business phone number display name verification outcomes.

phone_number_quality_update

The phone_number_quality_update webhook notifies you of changes to a business phone number’s throughput level.

security

The security webhook notifies you of changes to a business phone number’s security settings.

smb_app_state_sync

The smb_app_state_sync webhook is used for synchronizing contacts of WhatsApp Business app users who have been onboarded via a solution provider.

smb_message_echoes

The smb_message_echoes webhook notifies you of messages sent via the WhatsApp Business app or a companion (“linked”) device by a business customer who has been onboarded to Cloud API via a solution provider.

template_category_update

The template_category_update webhook notifies you of changes to template’s category.

user_preferences

The user_preferences webhook notifies you of changes to a WhatsApp user’s marketing message preferences.

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

Sample Chakra webhook event for an inbound text message

{
  "event": "message",
  "payload": {
    "wabaId": "83784929738012",
    "externalId": "wamid.HBgMOTE5OTAxMjU4NDMzFQIAEhgWM0VCMEQwQ0UyQTdCNkUyNTcxOEIwMAA=",
    "messageId": "wamid.HBgMOTE5OTAxMjU4NDMzFQIAEhgWM0VCMEQwQ0UyQTdCNkUyNTcxOEIwMAA=",
    "timestamp": 1788259051000,
    "message": {
      "from": "919911223344",
      "from_user_id": "IN.2363307770826624",
      "id": "wamid.HBgMOTE5OTAxMjU4NDMzFQIAEhgWM0VCMEQwQ0UyQTdCNkUyNTcxOEIwMAA=",
      "timestamp": "1788259051",
      "text": {
        "body": "bsuid_test_2"
      },
      "type": "text"
    },
    "contacts": [
      {
        "profile": {
          "name": "John"
        },
        "wa_id": "919911223344",
        "user_id": "IN.2363307770826624"
      }
    ]
  }
}

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#

List of supported webhook fields/events#

Chakra Events Webhook#

how to configure#

Inbound Event Object Structure#

Sample Chakra webhook event for an inbound text message#

HMAC Validation#

Step 1#

Step 2#

📄 Contents