Inbound Events Webhook

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

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

📄 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#

📄 Contents