Webhook Guide

Webhook Payload Structure

Incoming Message Event

Triggered when a customer sends a message to your business. Contains the message content, sender information, and metadata about the conversation. Use this to receive and process customer inquiries and responses in real-time.

Select Message Type

Simple text message from a customer

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "918123456789",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": { "name": "Sheena Nelson" },
                "wa_id": "919876543210"
              }
            ],
            "messages": [
              {
                "from": "919876543210",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
                "timestamp": "1749416383",
                "type": "text",
                "text": { "body": "Does it come in another color?" }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Message Status Event

Status webhooks notify you about the delivery and read status of messages you've sent. Track the journey of your messages from sent to delivered to read, and monitor any failures.

Select Message Status

Message successfully sent from servers

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "918123456789",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "status": "sent",
                "timestamp": "1750030073",
                "recipient_id": "919876543210",
                "conversation": {
                  "id": "72b14d6bd5407799e66f64d1b338e567",
                  "expiration_timestamp": "1750116480",
                  "origin": { "type": "marketing" }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "type": "regular",
                  "category": "marketing"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Status Values

Status	Description
sent	Message has been sent to WhatsApp servers
delivered	Message has been delivered to the recipient's device
read	Message has been read by the recipient
failed	Message delivery failed

Message Echoes Event

The smb_message_echoes webhook notifies you of messages sent via the WhatsApp Business app or a companion device. This allows you to track messages sent by your business across different channels and devices.

Example Payload

Outbound message sent by your business

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "message_echoes": [
              {
                "from": "15550783881",
                "to": "16505551234",
                "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA",
                "timestamp": "1739321024",
                "type": "text",
                "text": {
                  "body": "Here's the info you requested!"
                }
              }
            ]
          },
          "field": "smb_message_echoes"
        }
      ]
    }
  ]
}

Key Fields

Field	Description
field	Will always be "smb_message_echoes" for this event type
from	Your business phone number (sender)
to	Recipient's WhatsApp phone number
message_echoes	Array containing the messages sent by your business