Webhooks

This document describes webhooks and how they are used by the WhatsApp Business Platform.

Webhooks are HTTP requests containing JSON payloads that are sent from Meta's servers to a server of your designation. The WhatsApp Business Platform uses webhooks to inform you of incoming messages, the status of outgoing messages, and other important information, such as changes to your account status, messaging capability upgrades, and changes to your template quality scores.

For example, this is a webhook describing a message sent from a WhatsApp user to a business:

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

Create a webhook endpoint

To receive webhooks, you must create and configure a webhook endpoint. To create your own endpoint, see our Create a webhook endpoint document

If you aren't ready to create your own endpoint yet, you can create a test webhook endpoint that logs webhook payloads to the console. Note, however, that before you can use your app in a production capacity, you must create your own endpoint.

Permissions

You will need the following permissions to receive webhooks:

• whatsapp_business_messaging — for messages webhooks
• whatsapp_business_management — for all other webhooks

If you are a direct developer, use your system user to grant your app these permissions when generating your system token).

If you are a solution provider and need these permissions to provide appropriate services to your business customers, you must be approved for advanced access for the permissions via App Review before your business customers will be able to grant your app these permissions during onboarding.

Fields

Once you created and configured your webhook endpoint, you can subscribe to the following webhook fields.

Override webhooks

You can use an alternate webhook endpoint for messages webhooks for your WhatsApp Business Account (WABA) or business phone number. This can be useful for testing purposes, or if you are a solution provider and wish to use unique webhook endpoints for each of your onboarded customers.

See our Webhook overrides document to learn how to override webhooks.

Payload size

Webhook payloads can be up to 3 MB.

Webhook delivery failure

If we send a webhook request to your endpoint and your server responds with an HTTP status code other than 200, or if we are unable to deliver the webhook for another reason, we will keep trying with decreasing frequency until the request succeeds, for up to 7 days.

Note that retries will be sent to all apps that have subscribed to webhooks (and their appropriate fields) for the WhatsApp Business Account. This can result in duplicate webhook notifications.

IP addresses

You can get the IP addresses of our webhook servers by running the following command in your terminal:

whois -h whois.radb.net — '-i origin AS32934' | grep '^route' | awk '{print $2}' | sort

We periodically change these IP addresses so if you are allow-listing our servers you might want to occasionally regenerate this list and update your allow-list accordingly.

Troubleshooting

If you are not receiving webhooks:

• Make sure your endpoint is accepting requests.
• Send a test payload to your endpoint via the App Dashboard > WhatsApp > Configurations panel.
• Make sure your app is in Live mode; some webhooks will not be sent if your app is in Dev mode.

Learn more

• See our Using Node.js to implement webhooks WhatsApp Business blog post.