# Webhooks | Developer Documentation

<div id="bkmrk-webhooksupdated%3A-dec">## Webhooks

<div><span>Updated: Dec 2, 2025</span></div><div>This document describes webhooks and how they are used by the WhatsApp Business Platform.</div><div>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.</div><div>For example, this is a webhook describing a message sent from a WhatsApp user to a business:</div><div id="bkmrk-create-a-webhook-end"><div id="bkmrk-create-a-webhook-end-1"><div>### Create a webhook endpoint

</div></div></div><div>To receive webhooks, you must create and configure a webhook endpoint. To create your own endpoint, see our [Create a webhook endpoint](/books/meta-whatsapp/page/create-a-webhook-endpoint-developer-documentation) document</div><div>If you aren’t ready to create your own endpoint yet, you can [create a test webhook endpoint](/books/meta-whatsapp/page/create-a-test-webhook-endpoint-developer-documentation) 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.</div><div id="bkmrk-permissions"><div id="bkmrk-permissions-1"><div>### Permissions

</div></div></div><div>You will need the following permissions to receive webhooks:</div><span>**whatsapp\_business\_messaging** — for **messages** webhooks</span><span>**whatsapp\_business\_management** — for all other webhooks</span><div>If you are a direct developer, use your system user to grant your app these permissions when generating your [system token](/books/meta-whatsapp/page/access-tokens-guide-developer-documentation).</div><div>If you are a [solution provider](/books/meta-whatsapp/page/solution-providers-developer-documentation) 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](https://developers.facebook.com/docs/app-review) before your business customers will be able to grant your app these permissions during onboarding.</div><div id="bkmrk-fields"><div id="bkmrk-fields-1"><div>### Fields

</div></div></div><div>Once you [created and configured](/books/meta-whatsapp/page/create-a-webhook-endpoint-developer-documentation) your webhook endpoint (or have set up a [test webhook endpoint](/books/meta-whatsapp/page/create-a-test-webhook-endpoint-developer-documentation)), use the **[App Dashboard](/apps)** &gt; **WhatsApp** &gt; **Configuration** panel to subscribe to individual webhook fields.</div><div>Note that if you created your app using the **Connect with customers through WhatsApp** use case, navigate to **[App Dashboard](/apps)** &gt; **Use cases** &gt; **Customize** &gt; **Configuration** instead.</div><div><table><thead><tr><th><span>Field name </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>[account\_alerts](/documentation/business-messaging/whatsapp/webhooks/reference/account_alerts)</div></div></td><td><div><div>The **account\_alerts** webhook notifies you of changes to a business phone number’s [messaging limit](/books/meta-whatsapp/page/messaging-limits-developer-documentation), [business profile](/books/meta-whatsapp/page/business-phone-numbers-developer-documentation), and [Official Business Account](/books/meta-whatsapp/page/managing-whatsapp-business-accounts-developer-documentation) status.</div></div></td></tr><tr><td><div><div>[account\_review\_update](/documentation/business-messaging/whatsapp/webhooks/reference/account_review_update)</div></div></td><td><div><div>The **account\_review\_update** webhook notifies you when a WhatsApp Business Account has been reviewed against our policy guidelines.</div></div></td></tr><tr><td><div><div>[account\_update](/documentation/business-messaging/whatsapp/webhooks/reference/account_update)</div></div></td><td><div><div>The **account\_update** webhook notifies of changes to a WhatsApp Business Account’s [partner-led business verification](/books/meta-whatsapp/page/partner-led-business-verification-developer-documentation) submission, its [authentication-international rate](/books/meta-whatsapp/page/authentication-international-rates-developer-documentation) eligibility, or primary business location, when it is shared with a [Solution Partner](/books/meta-whatsapp/page/solution-providers-developer-documentation), [policy or terms violations](/books/meta-whatsapp/page/whatsapp-business-platform-policy-and-spam-enforcement-developer-documentation), offboarding, reconnection, or when it is deleted.</div></div></td></tr><tr><td><div><div>[automatic\_events](/books/meta-whatsapp/page/automatic-events-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **automatic\_events** webhook notifies you when we detect a purchase or lead event in a chat thread between you and a WhatsApp user who has messaged you via your Click to WhatsApp ad, if you have opted-in to [Automatic Events](/books/meta-whatsapp/page/automatic-events-api-developer-documentation) reporting.</div></div></td></tr><tr><td><div><div>[business\_capability\_update](/books/meta-whatsapp/page/business-capability-update-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **business\_capability\_update** webhook notifies you of WhatsApp Business Account or business portfolio capability changes ([messaging limits](/books/meta-whatsapp/page/messaging-limits-developer-documentation), [phone number limits](/books/meta-whatsapp/page/business-phone-numbers-developer-documentation), etc.).</div></div></td></tr><tr><td><div><div>[history](/books/meta-whatsapp/page/history-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **history** webhook is used to synchronize the [WhatsApp Business app chat history](/books/meta-whatsapp/page/onboarding-whatsapp-business-app-users-aka-coexistence-developer-documentation) of a business customer onboarded by a solution provider.</div></div></td></tr><tr><td><div><div>[message\_template\_components\_update](/books/meta-whatsapp/page/message-template-components-update-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **message\_template\_components\_update** webhook notifies you of changes to a template’s components.</div></div></td></tr><tr><td><div><div>[message\_template\_quality\_update](/books/meta-whatsapp/page/message-template-quality-update-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **message\_template\_quality\_update** webhook notifies you of changes to a template’s [quality score](/books/meta-whatsapp/page/template-quality-rating-developer-documentation).</div></div></td></tr><tr><td><div><div>[message\_template\_status\_update](/books/meta-whatsapp/page/message-template-status-update-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **message\_template\_status\_update** webhook notifies you of changes to the status of an existing template.</div></div></td></tr><tr><td><div><div>[messages](/books/meta-whatsapp/page/messages-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **messages** webhook describes messages sent from a WhatsApp user to a business and the status of messages sent by a business to a WhatsApp user.</div></div></td></tr><tr><td><div><div>[partner\_solutions](/books/meta-whatsapp/page/partner-solutions-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **partner\_solutions webhook** describes changes to the status of a [Multi-Partner Solution](/books/meta-whatsapp/page/multi-partner-solutions-developer-documentation).</div></div></td></tr><tr><td><div><div>[payment\_configuration\_update](/documentation/business-messaging/whatsapp/webhooks/reference/payment_configuration_update)</div></div></td><td><div><div>The **payment\_configuration\_update** webhook notifies you of changes to payment configurations for [Payments API India](/books/meta-whatsapp/page/payments-api-india-developer-documentation) and [Payments API Brazil](/books/meta-whatsapp/page/payments-api-brazil-developer-documentation).</div></div></td></tr><tr><td><div><div>[phone\_number\_name\_update](/books/meta-whatsapp/page/phone-number-name-update-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **phone\_number\_name\_update** webhook notifies you of business phone number [display name verification](/books/meta-whatsapp/page/display-names-developer-documentation) outcomes.</div></div></td></tr><tr><td><div><div>[phone\_number\_quality\_update](/books/meta-whatsapp/page/phone-number-quality-update-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **phone\_number\_quality\_update** webhook notifies you of changes to a business phone number’s [throughput level](/books/meta-whatsapp/page/throughput-developer-documentation).</div></div></td></tr><tr><td><div><div>[security](/books/meta-whatsapp/page/security-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **security** webhook notifies you of changes to a business phone number’s security settings.</div></div></td></tr><tr><td><div><div>[smb\_app\_state\_sync](/books/meta-whatsapp/page/smb-app-state-sync-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **smb\_app\_state\_sync** webhook is used for synchronizing contacts of [WhatsApp Business app users who have been onboarded](/books/meta-whatsapp/page/onboarding-whatsapp-business-app-users-aka-coexistence-developer-documentation) via a solution provider.</div></div></td></tr><tr><td><div><div>[smb\_message\_echoes](/books/meta-whatsapp/page/smb-message-echoes-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **smb\_message\_echoes** webhook notifies you of messages sent via the WhatsApp Business app or a [companion (“linked”) device](/books/meta-whatsapp/page/onboarding-whatsapp-business-app-users-aka-coexistence-developer-documentation) by a business customer who has been [onboarded to Cloud API](/books/meta-whatsapp/page/onboarding-whatsapp-business-app-users-aka-coexistence-developer-documentation) via a solution provider.</div></div></td></tr><tr><td><div><div>[template\_category\_update](/books/meta-whatsapp/page/template-category-update-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **template\_category\_update** webhook notifies you of changes to template’s [category](/books/meta-whatsapp/page/template-categorization-developer-documentation).</div></div></td></tr><tr><td><div><div>[user\_preferences](/books/meta-whatsapp/page/user-preferences-webhook-reference-developer-documentation)</div></div></td><td><div><div>The **user\_preferences** webhook notifies you of changes to a WhatsApp user’s [marketing message preferences](/books/meta-whatsapp/page/marketing-templates-developer-documentation).</div></div></td></tr></tbody></table>

</div><div id="bkmrk-override-webhooks"><div id="bkmrk-override-webhooks-1"><div>### Override webhooks

</div></div></div><div>You can use an alternate webhook endpoint for [certain webhook fields](/books/meta-whatsapp/page/webhook-overrides-developer-documentation) 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.</div><div>See our [Webhook overrides](/books/meta-whatsapp/page/webhook-overrides-developer-documentation) document to learn how to override webhooks.</div><div id="bkmrk-payload-size"><div id="bkmrk-payload-size-1"><div>### Payload size

</div></div></div><div>Webhook payloads can be up to 3 MB.</div><div id="bkmrk-webhook-delivery-fai"><div id="bkmrk-webhook-delivery-fai-1"><div>### Webhook delivery failure

</div></div></div><div>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.</div><div>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.</div><div id="bkmrk-mutual-tls"><div id="bkmrk-mutual-tls-1"><div>### Mutual TLS

</div></div></div><div>Webhooks support mutual TLS (mTLS) for added security. See Graph API’s [mTLS for webhooks](https://developers.facebook.com/docs/graph-api/webhooks/getting-started#mtls-for-webhooks) document to learn how to enable and use mTLS.</div><div id="bkmrk-ip-addresses"><div id="bkmrk-ip-addresses-1"><div>### IP addresses

</div></div></div><div>You can get the IP addresses of our webhook servers by running the following command in your terminal:</div><div>```
<span>whois </span><span>-</span><span>h whois</span><span>.</span><span>radb</span><span>.</span><span>net </span><span>—</span><span>'-i origin AS32934'</span><span>|</span><span> grep </span><span>'^route'</span><span>|</span><span> awk </span><span>'{print $2}'</span><span>|</span><span> sort</span>
```

</div><div>You can also use our geofeed to [download a CSV<span>⁠</span>](https://facebook.com/peering/geofeed) that lists our IP addresses.</div><div>Note, however, that we periodically change our IP addresses, so to avoid having to regenerate your list of allowed IP addresses, we recommend that you [use mTLS instead](https://developers.facebook.com/docs/graph-api/webhooks/getting-started#mtls-for-webhooks).</div><div id="bkmrk-troubleshooting"><div id="bkmrk-troubleshooting-1"><div>### Troubleshooting

</div></div></div><div>If you are not receiving webhooks:</div><span>Make sure your endpoint is accepting requests.</span><span>Send a test payload to your endpoint via the **[App Dashboard](/apps)** &gt; **WhatsApp** &gt; **Configurations** panel.</span><span>Make sure your app is in **Live** mode; some webhooks will not be sent if your app is in **Dev** mode.</span><span>Use our [test webhook endpoint](/books/meta-whatsapp/page/create-a-test-webhook-endpoint-developer-documentation). If the test endpoint is digesting webhook payloads and displaying them in the console, the issue is likely with your endpoint code.</span><div id="bkmrk-learn-more"><div id="bkmrk-learn-more-1"><div>### Learn more

</div></div></div><span>See our [Using Node.js to implement webhooks<span>⁠</span>](https://l.facebook.com/l.php?u=https%3A%2F%2Fbusiness.whatsapp.com%2Fblog%2Fhow-to-use-webhooks-from-whatsapp-business-api&h=AT4C0ozCf7Uf1GScM-Peo7UTch5DM-uWoYNWMnaFBGsBz-t9V0N4lmNqERQdATsT7Mk03cH913WESt8gvtMu8T1U3U4jzUXXs163NZub2vbPv54BZKh3uCn1TrkSCFrC3lra3v14Q4cFCseoa7f85w) WhatsApp Business blog post.</span></div>