WhatsApp Cloud API

Webhooks

WhatsApp Business Blog

Subscribe to Webhooks to get notifications about messages your business receives and customer profile updates.

Create an endpoint

Before you can start receiving notifications you will need to create an endpoint on your server to receive notifications.

Your endpoint must be able to process two types of HTTPS requests: Verification Requests and Event Notifications. Since both requests use HTTPs, your server must have a valid TLS or SSL certificate correctly configured and installed. Self-signed certificates are not supported.

Learn more about Verifying Requests and Event Notifications.

Subscribe to webhooks

To subscribe to Webhooks, you will need to get a Meta App ID and permissions. To do this go to the Meta App Dashboard. There you will:

  1. Create a Business Type App in the Meta App Dashboard.
  2. Add the Webhooks Product to your Meta app in the App Dashboard.

Permissions

In order to receive webhooks, you will need the following permissions:

If you are a solution provider and you need these webhooks in order to provide messaging services to onboarded business customers, you must be approved for advanced access for these permissions, via App Review.

Understanding webhooks

Whenever a trigger event occurs, the WhatsApp Business Platform sees the event and sends a notification to a Webhook URL you have previously specified. You can get two types of notifications:

  • Received messages: This alert lets you know when you have received a message. These can also be called "inbound notifications" throughout the documentation.
  • Message status and pricing notifications: This alert lets you know when the status of a message has changed —for example, the message has been read or delivered. These can also be called "outbound notifications" throughout the documentation.

All Webhooks have the following generic format:

{
  "object": "whatsapp_business_account",
  "entry": [{
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [{
          "value": {
              "messaging_product": "whatsapp",
              "metadata": {
                  "display_phone_number": "PHONE_NUMBER",
                  "phone_number_id": "PHONE_NUMBER_ID"
              },
              # specific Webhooks payload            
          },
          "field": "messages"
        }]
    }]
}

See Components for information on each field.

If you receive a message that is not supported for Cloud API, you will get an unknown message webhook.

Payload Size

Webhooks payloads can be up to 3MB.

Test webhook app

Deploy a test webhook app on Render.com if you are still testing and aren't yet ready to build your production webhook endpoint.

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 may 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.

Next Steps

Learn more about the information you can receive in a Webhooks notification.