FAQs: Webhooks | Zoho Desk

FAQ: Webhooks

1. What is a webhook?
A webhook is an automated message sent from Zoho Desk to a third-party application whenever a specific event occurs in your help desk. Instead of manually polling for updates or exporting data, webhooks push real-time notifications to a URL you designate, enabling instant cross-application communication.

For example, after closing a ticket, you can push the time-spent information to an accounting tool like QuickBooks to automatically generate an invoice. Or, when a new contact is added, user can trigger an API call to Mailchimp to add that contact to a seasonal mailing list.
2. How to create a webhook?
  1. Navigate to Setup > Developer Space > Webhooks.
  2. On the Webhooks List page, click Add your First Webhook or New Webhook.
  3. On the New Webhook page, fill in the following:
      1. Name: A descriptive name for your webhook.
      2. URL to Notify: The REST API URL of the third-party application (this is your callback URL).
      3. Description: Optional but recommended for clarity.
      4. Source ID: Must be entered in UUID format. This is used by the listener when performing other API-related actions.
  4. Under Choose Event, select the module, event, and department details.
  5. (Optional) Click the (+) icon to subscribe to multiple events for a single webhook.
  6. Click Test Run to validate the URL by posting a sample payload.
  7. Click Save.
Once saved, Zoho Desk will make an HTTP POST request to the endpoint URL whenever the chosen events are triggered.
3. What is the Source ID and why does it need to be in UUID format?
The Source ID is a unique identifier used by the listener (the receiving application or service) to correlate incoming webhook payloads with the correct source or context. It must be provided in UUID format (e.g., 550e8400-e29b-41d4-a716-446655440000). If you enter a non-UUID string, the webhook creation will fail or the listener may not be able to process the payload correctly.
4. Can a single webhook listen to multiple events?
Yes. When creating or editing a webhook, user can click the (+) icon under the Choose Event section to add and subscribe to multiple module-specific events. For instance, you could configure one webhook to fire on both "Ticket Add" and "Ticket Update without previous value" events, reducing the need to create separate webhooks for closely related triggers.
5. What does the Test Run feature do?
Test Run posts a sample payload to the URL you've entered, allowing you to verify that the endpoint is reachable and can accept the request before activating the webhook. This is especially useful for catching typos in the URL, confirming the endpoint is publicly accessible, and ensuring the receiving application can parse the payload structure.
6. Which modules support webhook events?
Webhooks support events across the following modules:
  1. Tickets
  2. Contacts
  3. Accounts
  4. Departments
  5. Agents
  6. Tasks
  7. Time Entry
  8. Articles
  9. KB Category
  10. KB Section
7. What types of events can be subscribed to within the Tickets module?
The Tickets module has the most extensive event support, including:
  1. Add — Triggered when a new ticket is created.
  2. Update specific fields with previous value — Fires when selected fields are updated, including the previous values.
  3. Update specific fields without previous value — Fires when selected fields are updated, excluding previous values.
  4. Update with previous value — Fires on any ticket update, including previous values.
  5. Update without previous value — Fires on any ticket update, excluding previous values.
  6. Delete — Triggered when a ticket is deleted.
  7. Incoming threads / Outgoing threads / All threads — Triggered when messages are received or sent on a ticket.
  8. Add comment / Update comment — Triggered on comment activity.
  9. Add attachment / Update attachment / Delete attachment — Triggered on attachment changes.
  10. Approval add / Approval update with previous value / Approval update without previous value — Triggered on approval workflow events.

8. What is the difference between "Update with previous value" and "Update without previous value"?
Update with previous value: The webhook payload includes both the old and new values of the changed fields. This is useful when the receiving application needs to know what changed (e.g., logging an audit trail or triggering conditional logic based on the delta).

Update without previous value: The payload includes only the new values. This is lighter and sufficient when the receiving application only needs the current state.

For example, if a ticket's status changes from "Open" to "Escalated," the "with previous value" payload would include old_status: Open, new_status: Escalated, while the "without previous value" payload would only include status: Escalated.
9. Do all modules support the same event types?
No, While most modules (Contacts, Accounts, Departments, Agents, Tasks, Time Entry, KB Category, KB Section) support Add, Update with previous value, Update without previous value, and Delete, the Tickets module has significantly more granular events (threads, comments, attachments, approvals). The Articles module additionally supports Translation events (add, update with/without previous value, delete) and Feedback add.
10. Can I use a webhook URL that requires authentication?
No, webhooks currently support only publicly accessible URLs that do not require authentication. If your endpoint requires basic auth, OAuth tokens, or API keys in headers, the webhook will not be able to deliver payloads successfully. You would need to set up an intermediary service (such as a serverless function) that accepts the unauthenticated POST from Zoho Desk and then forwards it to your authenticated endpoint.
11. Are webhook URLs with payloads in the URL supported?
No, Notify URLs with payloads in webhooks are not supported. The webhook sends data via an HTTP POST request body, not as URL parameters. If your third-party application expects data in the URL (e.g., as query string parameters), you will need an intermediary to transform the POST body into the expected format.
12. Can a webhook that was created through an extension be edited or deactivated?
No. Webhooks created via an extension cannot be edited or deactivated within Zoho Desk. They can only be managed (edited, deactivated) from within the extension itself. If you need to modify such a webhook, you'll need to access the extension's configuration or contact the extension developer.
13. What is the IM Message Status webhook event?
The IM Message Status event (eventType: IM_Message_Status) is triggered whenever the status of an individual instant message changes — for example, when a message moves from "Sent" to "Delivered," or from "Delivered" to "Read." This allows you to track the full message lifecycle across all IM channels (WhatsApp, Instagram, Facebook, chat).
14. What information is included in the IM Message Status payload?
The payload includes:
Field
Description
messageOldStatus
The previous status of the message
messageNewStatus.status
The updated status (SENT, DELIVERED, or READ)
messageNewStatus.updatedTime
The exact timestamp when the status changed
messageId
Unique identifier of the message
sessionId
Conversation/session ID the message belongs to
channelId
ID of the channel where the message was sent
eventTime
Timestamp of the webhook event
eventType
Type of webhook event (IM_Message_Status)
orgId
Zoho Desk organization ID
15. How to set up the IM Message Status webhook?
  1. Navigate to Setup > Automation > Webhooks.
  2. Click Create Webhook.
  3. Select the IM Message Status event.
  4. Enter your webhook URL.
  5. Save and test the webhook.
16. What are some practical use cases for the IM Message Status webhook?
  1. Delivery monitoring: Get alerted if messages are stuck in the SENT state for too long, indicating a potential delivery issue.
  2. Customer engagement tracking: Log every READ event to measure how often customers are reading your responses.
  3. Smart follow-ups: Trigger a follow-up task or reminder when a message is delivered but not read within a certain timeframe.
  4. Channel performance analytics: Compare delivery and read ratios across WhatsApp, Instagram, Facebook, and other IM channels to identify which channels drive the most engagement.
17. My webhook isn't firing. What should I check?
  1. Verify the webhook is active — Inactive webhooks do not send notifications.
  2. Confirm the event is correctly configured — Ensure the module, event type, and department match your trigger scenario.
  3. Check the URL accessibility — The endpoint must be publicly reachable without authentication.
  4. Use Test Run — Click Test Run to confirm the URL is valid and the endpoint can accept the payload.
  5. Check for payload-in-URL issues — If your Notify URL includes payload parameters, it won't work; the data is sent via POST body only.
  6. Verify edition and limits — Ensure you're on Professional or Enterprise and haven't exceeded the active webhook limit.
18. Why am I not receiving IM Message Status events?
  1. Confirm that IM channel supports message status callbacks — not all integrations may support this.
  2. Verify the webhook is enabled and the endpoint is reachable.
  3. Check that the channel's response mode and webhook settings are correctly configured (e.g., for LINE channels, the webhook must be enabled in the channel's Basic Settings tab).
19. How should I secure my webhook endpoint?
Since Zoho Desk webhooks do not support authenticated endpoints, consider these strategies:
  1. Use a unique, hard-to-guess URL path (e.g., https://yourapp.com/webhooks/zoho-desk/a7f3b2e9-...) to reduce the risk of unauthorized requests.
  2. Implement IP allowlisting on your server to only accept requests from Zoho's IP ranges.
  3. Validate the payload structure and content on your end to ensure the request is genuinely from Zoho Desk.
  4. Use an intermediary service (like AWS API Gateway + Lambda) that can receive the unauthenticated POST and then forward it securely to your internal systems.
20. Can webhooks be used with workflow rules or other automation features?
Webhooks operate independently as event-driven notifications, but they complement other automation features. For instance, you could use Zia's thread-level keywords to trigger workflow rules that change ticket priority or send notifications, while simultaneously using a webhook to push the same ticket data to an external CRM or analytics platform. The two systems work in parallel — webhooks do not interfere with or override workflow rules, and vice versa.
21. What HTTP method does Zoho Desk use to send webhook payloads?
Zoho Desk sends webhook payloads via HTTP POST requests to the specified Notify URL. The receiving endpoint should be configured to accept and parse POST requests.