Last updated: 2025-12-01

Source: https://support.freshdesk.com/support/solutions/articles/50000011592-manage-webhooks-for-whatsapp

WhatsApp Webhooks allow you to receive real-time, event-based notifications about the delivery status of outbound messages sent through the Freshdesk public API. This is critical for systems that need to track message success, measure customer engagement, and ensure data synchronization.

Webhook Setup and Configuration

To configure Webhooks for WhatsApp:

1. Log in to your account as admin. 2. Go to Admin > Channels > WhatsApp. 3. Click Manage Webhooks. 4. Enter the following details: - Destination URL (mandatory): The endpoint on your server where Freshdesk send the real-time message status updates (the webhook payload). The URL field is mandatory and must be a valid HTTPS URL format.

Example: https://webhooks.freshworks.com/freshdesk/whatsapp - Headers (Authentication & Custom Data - optional): Send necessary authentication tokens (like a Bearer token) or custom data along with the payload to your destination URL.

Enter the key/value pair. You can adda maximum of 3 Key-Value pairs, and once the limit is reached, the fields will be disabled. - Failed Notification Emails (optional): Allows you to receive email alerts if webhook delivery attempts fail after reaching the maximum number of retries.

You can add a maximum of two email addresses. An email alert will be sent only for the first webhook delivery failure in a day. Subsequent failures on the same day will not trigger additional emails.

Note: Ensure that you enter the email in a valid format. 5. Click Save.

This validates and stores your settings but does not activate the webhook. You can now see the Enabled/Disabled toggle at the top of the page. 6. To begin receiving message status updates, toggle the Enabled/Disabled option to enable.

The webhook is now active and will send outbound\_message\_event payloads to your destination URL in real-time.

Understanding the Webhook payload structure

All outbound message status updates use the outbound\_message\_event type and follow a consistent JSON structure.

Payload Fields


Field	Type	Description
version	String	The payload version.
account\_id	String	Your Freshdesk Account ID.
event\_type	String	The type of event. For message updates, this is always outbound\_message\_event.
event\_time	Timestamp	The time the webhook was generated by the Freshdesk server. This will be in the ISO 8601 format.<br>Example: 2025-11-18T09:25:46.167422931Z
actor	Object	The entity that caused the event (e.g., "type": "agent" or "type": "system").
data.message\_id	String	The unique ID of the message on the Freshdesk system.
data.external\_reference\_id	String	This field carries the value that was pushed by your system when the message was sent via API, allowing you to map the status back to a specific ticket or campaign.
data.status	String	The current delivery status of the message (see table below).
data.timestamp	Timestamp	The time the status change occurred (as reported by Meta/WhatsApp). This will be in the ISO 8601 format.<br>Example: 2025-11-18T09:25:46.167422931Z
data.error	Object	This object is only present upon message delivery failure and contains the corresponding error code and message.

Outbound Message Statuses

The data.status field provides a clear update on the message journey:


Status	Description	Sample Payload
QUEUED	The message has been successfully received by the Freshdesk platform and is awaiting submission to WhatsApp.	{<br>"version":"1.0.0",<br>"account\_id":"11011399037",<br>"account\_domain":"mm-fd.freshpo.com",<br>"event\_type":"outbound\_message\_event",<br>"event\_time":"2025-11-18T09:25:43.455954848Z",<br>"actor": {<br>"id":48046815001,<br>"name":"Maruthamuthu G",<br>"type":"agent"<br>},<br>"data": {<br>"external\_reference\_id":"MM-T1-00001",<br>"message\_id":"01KAB4HHTBE081898E432RCMA7",<br>"status":"QUEUED",<br>"timestamp":"2025-11-18T09:25:43.455951328Z"<br>}<br>}
SENT	The message has been successfully submitted to WhatsApp. This confirms the message is on its way to the user's phone.	{<br>"version":"1.0.0",<br>"account\_id":"11011399037",<br>"account\_domain":"mm-fd.freshpo.com",<br>"event\_type":"outbound\_message\_event",<br>"event\_time":"2025-11-18T09:25:46.167422931Z",<br>"actor": {<br>"id":0,<br>"name":"system",<br>"type":"system"<br>},<br>"data": {<br>"external\_reference\_id":"MM-T1-00001",<br>"message\_id":"01KAB4HHTBE081898E432RCMA7",<br>"status":"SENT",<br>"timestamp":"2025-11-18T09:25:45.885Z"<br>}<br>}
DELIVERED	The message has been successfully delivered to the recipient's WhatsApp application on their device.	{<br>"version":"1.0.0",<br>"account\_id":"11011399037",<br>"account\_domain":"mm-fd.freshpo.com",<br>"event\_type":"outbound\_message\_event",<br>"event\_time":"2025-11-18T09:25:47.835256615Z",<br>"actor": {<br>"id":0,<br>"name":"system",<br>"type":"system"<br>},<br>"data": {<br>"external\_reference\_id":"MM-T1-00001",<br>"message\_id":"01KAB4HHTBE081898E432RCMA7",<br>"status":"DELIVERED",<br>"timestamp":"2025-11-18T09:25:47.637Z"<br>}<br>}
READ	The recipient has opened and viewed the message in their WhatsApp conversation window.	{<br>"version":"1.0.0",<br>"account\_id":"11011399037",<br>"account\_domain":"mm-fd.freshpo.com",<br>"event\_type":"outbound\_message\_event",<br>"event\_time":"2025-11-18T09:26:44.058035219Z",<br>"actor": {<br>"id":0,<br>"name":"system",<br>"type":"system"<br>},<br>"data": {<br>"external\_reference\_id":"MM-T1-00001",<br>"message\_id":"01KAB4HHTBE081898E432RCMA7",<br>"status":"READ",<br>"timestamp":"2025-11-18T09:26:43.919Z"<br>}<br>}
FAILED	The message failed to be delivered to the recipient (e.g., due to an invalid number, the user being blocked, or a platform error).	{<br>"version":"1.0.0",<br>"account\_id":"11011399037",<br>"account\_domain":"mm-fd.freshpo.com",<br>"event\_type":"outbound\_message\_event",<br>"event\_time":"2025-11-18T10:18:32.387246015Z",<br>"actor": {<br>"id":0,<br>"name":"system",<br>"type":"system"<br>},<br>"data": {<br>"error": {<br>"code":"INVALID",<br>"message":"FAILED"<br>},<br>"message\_id":"01KAB4HHTBE081898E432RCMA7",<br>"status":"FAILED",<br>"timestamp":"2025-11-18T10:18:31.793Z"<br>}<br>}