Webhook events and notifications
Last updated
Last updated
Real-time notifications sent to your Partner Webhook about the management of WABAs and phone numbers associated with your Partner Account.
After your Partner Hub Webhook URL is configured, you will start receiving these Webhook events.
The events shared today are:
This event is submitted to a partner's webhook when a new client registers under their hub.
The field event will have client_created value set.
This event is triggered every time a new channel is created under your 360dialog Partner Hub. This is the first event created after the client finishes signup.
The field event will have channel_created value set.
You will be able to identify which client created this channel in the client_id and client fields. You are also able to see the phone number (phone_number field) and display name (phone_name field) registered in this channel.
Under the field created_at you can see when was the account created and under billing_started_at you can see when the billing started.
You can also see the current Business Manager status of this account under fb_account_status and the account status under status and account_mode.
This event is submitted to a partner's webhook when a number is ready to be registered.
Field event will have channel_ready value set.
This event is submitted to a partner's webhook when a new number transitions into running state.
Field event will have channel_running value set.
This event is triggered every time a new channel submitted under your 360 Partner Hub goes live.
The field event will have channel_live value set.
You will be able to identify which client created this channel in the client_id and client fields. You are also able to see the phone number (phone_number field) and display name (phone_name field) registered in this channel.
Under the field created_at you can see when was the account created and under billing_started_at you can see when the billing started.
You can also see the current Business Manager status of this account under fb_account_status and the account status under status and account_mode.
This event is triggered every time a client grants permission for their number, meaning that you can now request the API Key for this specific channel.
The field event will have channel_permission_granted value set.
You will be able to identify which client created this channel in the client_id and client fields. You are also able to see the phone number (phone_number field) and display name (phone_name field) registered in this channel.
This event is triggered every time a client revokes permission for their number.
The field event will have channel_permission_revoked value set.
You will be able to identify which client created this channel in the client_id and client fields. You are also able to see the phone number (phone_number field) and display name (phone_name field) registered in this channel.
This event is triggered when a channel subscription is set, meaning when the billing starts for this channel.
The field event will have channel_subscription_set value set.
You will be able to identify which client created this channel in the client_id and client fields. You are also able to see the phone number (phone_number field) and display name (phone_name field) registered in this channel.
This event is triggered every time a client requests a channel cancellation.
The field event will have cancellation_request value set.
You will be able to identify which client created this channel in the client_id and client fields. You are also able to see the phone number (phone_number field) and display name (phone_name field) registered in this channel.
This event is triggered every time a client revokes a channel cancellation.
The field event will have cancellation_revoke value set.
You will be able to identify which client created this channel in the client_id and client fields. You are also able to see the phone number (phone_number field) and display name (phone_name field) registered in this channel.
This event is triggered every time a client cancellation request is processed and the phone number is deleted.
The field event will have cancellation_processed value set.
You will be able to identify which client created this channel in the client_id and client fields. You are also able to see the phone number (phone_number field) and display name (phone_name field) registered in this channel.
Right after signup, after the channel is live, it is temporarily disabled for template message sending. Each channel goes through internal 360dialog review and, if valid, will have template messaging enabled in up to 2 hours.
When a channel is enabled for template messaging, the partner will receive this event.
Field event will have template_messaging_enabled value set.
This event is submitted when the hosting platform type changes.
Field event will have either migrated_to_cloud_api or migrated_to_on_premise value set if there was migration from On-premise to Cloud API or vice versa.
As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025.
Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches. From May 15, 2024, 360dialog will not allow for new numbers to be onboarded with On-Premise API. We will continue supporting already registered On-Premise API throughout 2024, but we strongly recommend to start changing the hosting type of numbers to Cloud as soon as possible. Learn here how to integrate with Cloud API.
This event is submitted to a partner's webhook when a client's account is restricted.
The field event will have account_violation value set.
You will be able to identify which account was restricted by the value phone_number. There will also be violation_type and violation_info, which indicates what made the account be restricted.
This event is submitted to a partner's webhook when a client's account is banned.
The field event will have DISABLED_UPDATE value set.
This event is submitted to a partner's webhook when a client's account is restricted.
The field event will have account_restriction value set.
You will be able to identify which account was restricted by the value phone_number. There will also be violation_type, which indicates what made the account be restricted.
This event is submitted to a partner's webhook when numbers quality rating changes and we receive a callback from Meta.
Field event will have phone_number_quality_changed value set. Also in data object, there will be an extra property called current_quality_update_event to tell the type of event received from FB. Examples of events are flagged, etc.
A template status can change automatically, based on a review decision, appeal outcome, or a change to its quality rating. Webhooks are sent with the following structure:
The template payload structure depends on the type of the template update:
Template Quality Score Changed
The field event will have waba_template_quality_score_changed value set. See Quality Rating.
Template Status Changed
The field event will have waba_template_status_changed value set. See Template Statuses.
Template Category Changed
The field event will have waba_template_category_changed value set. See Template Categories.
This event is submitted to partner's webhook when flow's endpoint availability reaches the threshold.
Field event will have ENDPOINT_AVAILABILITY value set.
This event is submitted to partner's webhook when flow's client error rate reaches the threshold.
Field event will have CLIENT_ERROR_RATE value set.
This event is submitted to partner's webhook when flow's endpoint error rate reaches the threshold.
Field event will have ENDPOINT_ERROR_RATE value set.
This event is submitted to partner's webhook when flow's endpoint latency reaches the threshold.
Field event will have ENDPOINT_LATENCY value set.
This event is submitted to partner's webhook when flow's status is changed.
Field event will have FLOW_STATUS_CHANGE value set.
After the webhook is set for the number, it will receive notifications about messaging events. These events are grouped and can be used for:
Inbound Message Notifications: Use it to get a notification when a customer performs an action, such as:
|
|
Message Status Notifications: Use it to monitor the status of sent messages.
|
|
|
If a webhook event isn't delivered for any reason (e.g., the client is offline) or if the webhook request returns a HTTP status code other than 200, we retry the webhook delivery. We continue retrying delivery with increasing delays up to a certain timeout (typically 24 hours, though this may vary), or until the delivery succeeds.
For Cloud API, the object is always whatsapp_business_account but the field will be indicative of the type of information being sent.
[will be deprecated] For On-premise API, the object will be contacts and messages, errors, or statuses and pricing.
See Text Messages.
The following is an example of a text message you received from a customer:
See Reaction Messages.
The following is an example of a reaction message you received from a customer. You will not receive this webbook if the message the customer is reacting to is more than 30 days old.
Note that for reactions, the timestamp value indicates when the customer sent the reaction, not when the webhook was generated.
See Media Messages.
When a message with media is received, the WhatsApp Business Platform downloads the media. A notification is sent to the Webhook once the media is downloaded.
The Webhook notification contains information that identifies the media object and enables you to find and retrieve the object. Use the media endpoints to retrieve the media.
It's possible to receive an unknown message callback notification. For example, a customer could send you a message that's not supported, such as a disappearing message (in which case Meta notifies the that the message type is not supported).
See Location Messages.
The following is an example of a location message you received from a customer:
See Contacts Messages.
The following is an example of a contact message you received from a customer:
When your customer clicks on a quick reply button in an interactive message template, a response is sent. Below is an example of the callback format.