TABLE OF CONTENTS
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:
- Log in to your account as admin.
- Go to Admin > Channels > WhatsApp.
- Click Manage Webhooks.
- 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 add a 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.
- 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.
- 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. - 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. 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. 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. | { "version":"1.0.0", "account_id":"11011399037", "account_domain":"mm-fd.freshpo.com", "event_type":"outbound_message_event", "event_time":"2025-11-18T09:25:43.455954848Z", "actor": { "id":48046815001, "name":"Maruthamuthu G", "type":"agent" }, "data": { "external_reference_id":"MM-T1-00001", "message_id":"01KAB4HHTBE081898E432RCMA7", "status":"QUEUED", "timestamp":"2025-11-18T09:25:43.455951328Z" } } |
SENT | The message has been successfully submitted to WhatsApp. This confirms the message is on its way to the user's phone. | { "version":"1.0.0", "account_id":"11011399037", "account_domain":"mm-fd.freshpo.com", "event_type":"outbound_message_event", "event_time":"2025-11-18T09:25:46.167422931Z", "actor": { "id":0, "name":"system", "type":"system" }, "data": { "external_reference_id":"MM-T1-00001", "message_id":"01KAB4HHTBE081898E432RCMA7", "status":"SENT", "timestamp":"2025-11-18T09:25:45.885Z" } } |
DELIVERED | The message has been successfully delivered to the recipient's WhatsApp application on their device. | { "version":"1.0.0", "account_id":"11011399037", "account_domain":"mm-fd.freshpo.com", "event_type":"outbound_message_event", "event_time":"2025-11-18T09:25:47.835256615Z", "actor": { "id":0, "name":"system", "type":"system" }, "data": { "external_reference_id":"MM-T1-00001", "message_id":"01KAB4HHTBE081898E432RCMA7", "status":"DELIVERED", "timestamp":"2025-11-18T09:25:47.637Z" } } |
READ | The recipient has opened and viewed the message in their WhatsApp conversation window. | { "version":"1.0.0", "account_id":"11011399037", "account_domain":"mm-fd.freshpo.com", "event_type":"outbound_message_event", "event_time":"2025-11-18T09:26:44.058035219Z", "actor": { "id":0, "name":"system", "type":"system" }, "data": { "external_reference_id":"MM-T1-00001", "message_id":"01KAB4HHTBE081898E432RCMA7", "status":"READ", "timestamp":"2025-11-18T09:26:43.919Z" } } |
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). | { "version":"1.0.0", "account_id":"11011399037", "account_domain":"mm-fd.freshpo.com", "event_type":"outbound_message_event", "event_time":"2025-11-18T10:18:32.387246015Z", "actor": { "id":0, "name":"system", "type":"system" }, "data": { "error": { "code":"INVALID", "message":"FAILED" }, "message_id":"01KAB4HHTBE081898E432RCMA7", "status":"FAILED", "timestamp":"2025-11-18T10:18:31.793Z" } } |