Webhooks
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:
Permissions
In order to receive webhooks, you will need the following permissions:
- whatsapp_business_messaging — for
messageswebhooks - whatsapp_business_management — for all other webhooks
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.
Fields
You can subscribe to the following webhook fields.
| Field name | Description |
|---|---|
The account_alerts webhook notifies you of changes to a business phone number's messaging limit, business profile, and Official Business Account status. | |
The account_review_update webhook notifies you when a WhatsApp Business Account has been reviewed against our policy guidelines. | |
The account_update webhook notifies of changes to a WhatsApp Business Account's partner-led business verification submission, its authentication-international rate eligibility or primary business location, when it is shared with a solution provider, policy or terms violations, or when it is deleted. | |
The business_capability_update webhook notifies you of WhatsApp Business Account or business portfolio capability changes (messaging limits, phone number limits, etc.). | |
The history webhook is used to synchronize the WhatsApp Business app chat history of a business customer onboarded by a solution provider. | |
The message_template_components_update webhook notifies you of changes to a template's components. | |
The message_template_quality_update webhook notifies you of changes to a template's quality score. | |
The message_template_status_update webhook notifies you of changes to the status of an existing template. | |
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. | |
The partner_solutions webhook describes changes to the status of a Multi-Partner Solution. | |
The payment_configuration_update webhook notifies you of changes to payment configurations for Payments API India and Payments API Brazil. | |
The phone_number_name_update webhook notifies you of business phone number display name verification outcomes. | |
The phone_number_quality_update webhook notifies you of changes to a business phone number's messaging limit and throughput level. | |
The security webhook notifies you of changes to a business phone number's security settings. | |
The smb_app_state_sync webhook is used for synchronizing contacts of WhatsApp Business app users who have been onboarded via a solution provider. | |
The smb_message_echoes webhook notifies you of messages sent via the Whatsapp Business app or a companion ("linked") device by a business customer who has been onboarded to Cloud API via a solution provider. | |
The template_category_update webhook notifies you of changes to template's category. | |
The user_preferences webhook notifies you of changes to a WhatsApp user's marketing message preferences. |
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.
See Also
- WhatsApp Business Blog – Using Node.js to implement webhooks
- AI
- Meta Horizon OS
- Social technologies
- Wearables
Build with Meta
- Responsible platform initiatives
- Platform terms
- Developer policies
