WhatsApp Cloud API incoming message webhook payload example

WhatsApp Cloud API (Meta) · event: messages (incoming text) · content type: application/json

This is a representative sample — fake IDs, real structure. To see a payload with your data, point the provider at a capture URL (button below).

See it live, not frozen

One click creates a free capture bin with this exact payload already in it — pretty-printed, headers inspectable, replayable to your own endpoint:

Then paste the bin's URL into WhatsApp Cloud API (Meta)'s webhook settings to capture a real delivery. No signup.

Headers

content-type: application/json
x-hub-signature-256: sha256=fffa17664ad5ad907b010b4eaa338d17d383bbc61a3c2f75b5ed5b7469cff514

Body

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550559999",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Ada Lovelace"
                },
                "wa_id": "15551234567"
              }
            ],
            "messages": [
              {
                "from": "15551234567",
                "id": "wamid.HBgLMTU1NTEyMzQ1NjcVAgASGBQzQTdCRjc4RDlEMEE1QzZERkQ2AA==",
                "timestamp": "1787990000",
                "text": {
                  "body": "Hi! Has my order shipped yet?"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Things that bite people

This example's signature actually verifies: paste the body, the header value, and the App Secret a1b2c3d4e5f60718293a4b5c6d7e8f90 into the signature debugger — Meta uses GitHub's exact scheme (sha256= + hex HMAC-SHA256 of the raw body), keyed with your App Secret.
Before any of this arrives, Meta sends a GET handshake with hub.mode / hub.verify_token / hub.challenge query params — you must echo hub.challenge as plaintext. That step is where most setups die: WhatsApp webhook verification failed.
Everything is nested three levels deep (entry[] → changes[] → value) and both arrays can carry multiple items — iterate, don't index [0].
Only a 200 counts as delivered; anything else is retried with exponential backoff for up to 7 days. Message timestamp is a string of epoch seconds.

Send it yourself

Reproduce this delivery against any endpoint (your handler, a bin, staging):

$ curl -X POST https://your-endpoint.example/hook \
  -H 'content-type: application/json' \
  -H 'x-hub-signature-256: sha256=fffa17664ad5ad907b010b4eaa338d17d383bbc61a3c2f75b5ed5b7469cff514' \
 -d '{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550559999",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Ada Lovelace"
                },
                "wa_id": "15551234567"
              }
            ],
            "messages": [
              {
                "from": "15551234567",
                "id": "wamid.HBgLMTU1NTEyMzQ1NjcVAgASGBQzQTdCRjc4RDlEMEE1QzZERkQ2AA==",
                "timestamp": "1787990000",
                "text": {
                  "body": "Hi! Has my order shipped yet?"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}'

← All payload examples · Related guide · Signature debugger · Docs