Partner Webhook Events (associated with Partner API)
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:
Client Account created
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.
Example payload
Channel created
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.
Example payload
Channel ready
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.
Example Payload
Channel running
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.
Example Payload
Channel live
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.
Example payload
Channel permission granted
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.
Example payload
Channel permission revoked
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.
Example payload
Channel subscription was set
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.
Example payload
Cancellation request
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.
Example payload
Cancellation revoked
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.
Example payload
Cancellation processed
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.
Example payload
Channel enabled for template messaging
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.
Example payload
Hosting platform type change
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.
Example payload
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.
Account violation
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, which indicates what made the account be restricted.
Example payload
Account restriction
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.
Example payload
Account review
A notification is sent when the WhatsApp Business Account has been reviewed.
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.
Example payload
Message Template Status Update
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:
Inbound Message Notifications: Use it to get a notification when a customer performs an action, such as:
Sends a text message to the business
Sends an image, video, audio, document, or sticker to the business
Sends contact information to the business
Sends location information to the business
Clicks a reply button set up by the business
Clicks a call-to-actions button on an Ad that Clicks to WhatsApp
Clicks an item on a business' list
Updates their profile information such as their phone number
Asks for information about a specific product
Orders products being sold by the business
Message Status Notifications: Use it to monitor the status of sent messages.
delivered
read
sent
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.
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.
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.
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).
Example Payload
The following is an example of a message you received from a customer that is not supported.
{"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" },"contacts": [{"profile": { "name":"NAME" },"wa_id":"WHATSAPP_ID" }],"messages": [{"from":"PHONE_NUMBER","id":"wamid.ID","timestamp":"TIMESTAMP","errors": [ { "code":131051,"details":"Message type is not currently supported","title":"Unsupported message type" }],"type":"unknown" }] }"field": "messages" }], }]}
When the user completes the flow, a message is sent to WhatsApp chat. You will receive that message through a webhook which you normally use to process chat messages from the user.
Messages will have one of the following statuses which will be returned in each of the messages objects
"message_status":"accepted" : means the message was sent to the intended recipient.
"message_status":"held_for_quality_assessment": means the message send was delayed until quality can be validated and it will either be sent or dropped at this point.
{"messaging_product":"whatsapp","contacts": [ {"input":"16505555555","wa_id":"16505555555" } ],"messages": [ {"id":"wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA","message_status":"Message has been held because quality assessment is pending",//"message_status": "accepted", } ] }
Message Status Updates
The Messaging webhook receives an event when the message is sent, delivered, and read.
The order of these events may not reflect the actual timing of the message status. View the timestamp to determine the timing, if necessary.
Status: Message Sent
The following notification is received when a business sends a message as part of a user-initiated conversation (if that conversation did not originate in a free entry point):
The following notification is received when a business’ message is delivered and that message is part of a user-initiated conversation (if that conversation did not originate in a free entry point):
Currently, the Cloud API does not support webhook status updates for deleted messages. If a user deletes a message, you will receive a webhook with an error code for an unsupported message type:
Example Payload
{"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 },"contacts": [{"profile": {"name":"NAME" },"wa_id": PHONE_NUMBER }],"messages": [{"from": PHONE_NUMBER,"id":"wamid.ID","timestamp": TIMESTAMP,"errors": [{"code":131051,"details":"Message type is not currently supported","title":"Unsupported message type" }],"type":"unsupported" }] },"field":"messages" }] }]}
Please note that there are other user behaviors that can trigger this same error message. See Error Messages.
{"object":"whatsapp_business_account","entry": [ {"id":"102290129340398 ","changes": [ {"value": {"messaging_product":"whatsapp","metadata": {"display_phone_number":"15550783881","phone_number_id":"106540352242922" },"statuses": [ {"id":"wamid.HBgLMTIxMTU1NTc5NDcVAgARGBIyRkQxREUxRDJFQUJGMkQ3NDIA","status":"failed","timestamp":"1689380458","recipient_id":"15551234567","errors": [ {"code":130472,"title":"User's number is part of an experiment","message":"User's number is part of an experiment","error_data": {"details":"Failed to send message because this user's phone number is part of an experiment" },"href":"https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/" } ] } ] },"field":"messages" } ] } ]}
