Zendesk webhooks

Zendesk webhooks are HTTP requests that Zendesk sends to your URL when activity happens in Support, Guide, Gather or Messaging, either for events you subscribe to or when a trigger or automation runs.

142 events covered

These pages list the events a webhook subscribed to Zendesk events receives. A webhook connected to a trigger or automation sends the request you define, a JSON or XML body or URL parameters, with no type field but the same signature headers. To send events into Zendesk instead, see ZIS inbound webhooks.

How Zendesk webhooks work

Zendesk pushes activity to you, so you don't have to poll its APIs. Each webhook uses one of two connection methods, and you can't change it later. A webhook subscribed to Zendesk events always sends a POST with a fixed JSON body. A webhook connected to a trigger or automation sends the HTTP method, format and content you define, using placeholders for ticket data, so it has no event type or shared schema.

In an event body, type names the event, such as zen:event-type:ticket.created. detail holds the resource, event holds what changed, subject names the resource and id identifies the event. zendesk_event_version records the event's schema version, which you don't choose. Zendesk queues each webhook as a job and runs jobs independently, so a request can arrive late or out of order. Every request also carries x-zendesk-account-id, x-zendesk-webhook-id and x-zendesk-webhook-invocation-id.

Key facts

Signature header
X-Zendesk-Webhook-Signature

Format: <base64 HMAC-SHA256>

Scheme
HMAC-SHA256, base64
Signed material
{timestamp}{raw body}

The X-Zendesk-Webhook-Signature-Timestamp value exactly as sent, followed directly by the body, with no separator. A request with no body, such as a GET or DELETE from a trigger webhook, signs the timestamp alone.

How events are identified
type in the body; none on trigger or automation webhooks
Body format
JSON
API versioning
zendesk_event_version in the body

Seen: 2022-06-20, 2022-11-06, 2022-12-06.

Send timestamp
X-Zendesk-Webhook-Signature-Timestamp
Other headers
x-zendesk-account-id, x-zendesk-webhook-id, x-zendesk-webhook-invocation-id, x-zendesk-webhook-signature-timestamp
Envelope
type, account_id, id, time, zendesk_event_version, subject, detail, event
Agent skill
npx skills add hookdeck/webhook-skills --skill zendesk-webhooks

Verify Zendesk webhooks →

Setting up Zendesk webhooks

  • Create a webhook in Admin Center under Apps and integrations > Webhooks > Webhooks, or with POST /api/v2/webhooks. Choose Zendesk events or a trigger or automation at the start, because you can't switch later.
  • An event webhook lists its event types in subscriptions. A trigger or automation webhook sets subscriptions to conditional_ticket_events, and you define its content in the trigger or automation's notification_webhook action.
  • Test from the webhook's Test webhook option in Admin Center, which sends a request you can edit and shows the response, or with POST /api/v2/webhooks/test. To tunnel real events to localhost, use the Hookdeck CLI: hookdeck listen 3000 zendesk --path /webhooks/zendesk.
  • Zendesk documents no way to resend a request. GET /api/v2/webhooks/{webhook_id}/invocations lists the last 7 days of invocations, and each invocation's attempts are available under it.

Delivery behaviour

  1. A slow handler gets the same request again

    Zendesk gives a request 12 seconds and retries a timeout up to five times, so slow work can run more than once. Respond first and process the event from a queue.

    Handle timeouts →
  2. Duplicates, even without a failure

    Zendesk tries to deliver once but doesn't guarantee it, and one action can invoke a webhook several times. Deduplicate on the body's id for event webhooks, and on a key you add to the payload for trigger webhooks.

    Handle duplicates →
  3. A 500 isn't retried

    Zendesk lists retries for a 409, for a 429 or 503 with a retry-after under 60 seconds, and for timeouts. It lists none for other errors such as a 500, so plan to reconcile from its APIs after an outage.

    Retries and lost events →
  4. The circuit breaker drops events

    If 70% of a webhook's requests fail within five minutes, or it gets more than 1,000 error responses, Zendesk pauses it for five seconds at a time until a request succeeds. Invocations during a pause are logged as circuit broken, and those events may never be delivered.

    Retries and lost events →

Zendesk webhook best practices

Common Zendesk webhook events

Tickets

zen:event-type:ticket.created New ticket is opened
zen:event-type:ticket.status_changed Ticket's status moves to another value
zen:event-type:ticket.comment_added Comment is added as a ticket is created or updated
zen:event-type:ticket.agent_assignment_changed Ticket moves to a different agent

Users and organizations

zen:event-type:user.created New user is added
zen:event-type:user.deleted User is removed
zen:event-type:organization.created New organization is added
zen:event-type:organization.deleted Organization is removed

Help center

zen:event-type:article.published Help center article goes live
zen:event-type:article.unpublished Help center article is withdrawn

Events by resource

Resource Events Payloads
ticket

zen:event-type:ticket.created · zen:event-type:ticket.status_changed · zen:event-type:ticket.comment_added · zen:event-type:ticket.priority_changed +33

37 37
messaging_live_metrics

zen:event-type:messaging_live_metrics.active_assigned_all · zen:event-type:messaging_live_metrics.active_assigned_group · zen:event-type:messaging_live_metrics.active_in_queue_all · zen:event-type:messaging_live_metrics.active_in_queue_group +29

33 32
user

zen:event-type:user.created · zen:event-type:user.alias_changed · zen:event-type:user.custom_field_changed · zen:event-type:user.custom_role_changed +23

27 27
community_post

zen:event-type:community_post.created · zen:event-type:community_post.changed · zen:event-type:community_post.published · zen:event-type:community_post.unpublished +10

14 14
article

zen:event-type:article.author_changed · zen:event-type:article.published · zen:event-type:article.subscription_created · zen:event-type:article.unpublished +7

11 11
agent

zen:event-type:agent.state_changed · zen:event-type:agent.work_item_added · zen:event-type:agent.work_item_updated · zen:event-type:agent.work_item_removed +5

9 9
organization

zen:event-type:organization.created · zen:event-type:organization.custom_field_changed · zen:event-type:organization.deleted · zen:event-type:organization.external_id_changed +2

6 6
messaging

zen:event-type:messaging_ticket.message_added · zen:event-type:chat_ticket.member_joined · zen:event-type:chat_ticket.listening_agents_changed

3 3

1 more resource, including Other Zendesk events. All 142 events →

In this hub

Webhook events → Every covered Zendesk event, with payloads where the registry has them.
MCP events → How an agent subscribes to Zendesk events as MCP events.
Verify signatures → Signature facts, verification code and common failures.
Production guide → Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
Agent skill → Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill zendesk-webhooks

Keep Zendesk's circuit breaker from dropping your events.

Hookdeck Event Gateway accepts each Zendesk delivery, verifies its signature, queues it and retries to your service on your schedule, and keeps a log of every attempt so you can replay what failed.

Not affiliated with Zendesk. Facts are compiled from public sources and linked inline.