# 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.

These pages list the events a webhook subscribed to Zendesk events receives. A webhook connected to a [trigger or automation](https://developer.zendesk.com/documentation/webhooks/creating-and-monitoring-webhooks/#connecting-a-webhook-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](https://developer.zendesk.com/api-reference/integration-services/inbound-webhooks/inbound_webhooks/).

Agent skill: `npx skills add hookdeck/webhook-skills --skill zendesk-webhooks` ([details](https://hookdeck.com/webhooks/zendesk/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Zendesk's official docs](https://developer.zendesk.com/api-reference/event-connectors/webhooks/webhook-event-types/).

[Overview](https://hookdeck.com/webhooks/zendesk) · [Webhook events (142)](https://hookdeck.com/webhooks/zendesk/events) · [MCP events](https://hookdeck.com/webhooks/zendesk/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/zendesk/verify) · [Production guide](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/zendesk/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `X-Zendesk-Webhook-Signature` Format: <base64 HMAC-SHA256> | [Zendesk docs](https://developer.zendesk.com/documentation/webhooks/verifying/) |
| Scheme | `HMAC-SHA256, base64` | [Zendesk docs](https://developer.zendesk.com/documentation/webhooks/verifying/) |
| 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. | [Zendesk docs](https://developer.zendesk.com/documentation/webhooks/verifying/) |
| How events are identified | `type in the body; none on trigger or automation webhooks` | [Zendesk docs](https://developer.zendesk.com/api-reference/webhooks/event-types/webhook-event-types/) |
| Body format | `JSON` | [Zendesk docs](https://developer.zendesk.com/documentation/webhooks/anatomy-of-a-webhook-request/) |
| API versioning | `zendesk_event_version in the body` Seen: 2022-06-20, 2022-11-06, 2022-12-06. | [Zendesk docs](https://developer.zendesk.com/api-reference/webhooks/event-types/webhook-event-types/) |
| Send timestamp | `X-Zendesk-Webhook-Signature-Timestamp` | [Zendesk docs](https://developer.zendesk.com/documentation/webhooks/verifying/) |
| Other headers | `x-zendesk-account-id, x-zendesk-webhook-id, x-zendesk-webhook-invocation-id, x-zendesk-webhook-signature-timestamp` | [Zendesk docs](https://developer.zendesk.com/api-reference/event-connectors/webhooks/webhook-event-types/) |
| Envelope | `type, account_id, id, time, zendesk_event_version, subject, detail, event` | [Zendesk docs](https://developer.zendesk.com/api-reference/event-connectors/webhooks/webhook-event-types/) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill zendesk-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/zendesk/skill) |

[Verify Zendesk webhooks](https://hookdeck.com/webhooks/zendesk/verify)

## 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`.

## 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

- **Timeout:** 12 seconds. a request that times out is retried up to five times. [Guide](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** some failures. 409 up to three times, timeouts up to five, and 429 or 503 with a `retry-after` under 60 seconds. [Guide](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries:** no resend. the activity log keeps 7 days of invocations, and Zendesk describes no replay. [Guide](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** not guaranteed. webhook jobs run independently, so compare `time`. [Guide](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

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](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts#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](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts#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](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts#retries)
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](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts#retries)

From [Hookdeck's Zendesk guide](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts).

## Zendesk webhook best practices

- **[Verify the signature over the raw body](https://hookdeck.com/webhooks/zendesk/verify).** Sign the timestamp header followed by the bytes you received, and keep the real signing secret out of your code.
- **[Return a 2xx within 12 seconds](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts#timeouts).** Zendesk retries a timed-out request up to five times, so queue the work and respond first.
- **[Deduplicate on your own key](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts#duplicates).** Record the body's `id` on event webhooks, and add a key to the payload you write for a trigger or automation.
- **[Don't rely on arrival order](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts#ordering).** Webhook jobs run independently. Compare `time` for each `subject`, or fetch the current record.
- **[Ask for a retry when you can't accept a request](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts#retries).** A 503 with a `retry-after` under 60 seconds is retried, while Zendesk lists no retry for a plain 500.
- **[Check the invocation log yourself](https://hookdeck.com/webhooks/zendesk/guide-duplicates-ordering-retries-timeouts#retries).** Zendesk's docs describe no failure alerts, so poll failed and `circuit broken` invocations within the 7 days it keeps them.

## Common Zendesk webhook events

### Tickets

- [zen:event-type:ticket.created](https://hookdeck.com/webhooks/zendesk/events/ticket#zen%3Aevent-type%3Aticket.created): New ticket is opened
- [zen:event-type:ticket.status_changed](https://hookdeck.com/webhooks/zendesk/events/ticket#zen%3Aevent-type%3Aticket.status_changed): Ticket's status moves to another value
- [zen:event-type:ticket.comment_added](https://hookdeck.com/webhooks/zendesk/events/ticket#zen%3Aevent-type%3Aticket.comment_added): Comment is added as a ticket is created or updated
- [zen:event-type:ticket.agent_assignment_changed](https://hookdeck.com/webhooks/zendesk/events/ticket#zen%3Aevent-type%3Aticket.agent_assignment_changed): Ticket moves to a different agent

### Users and organizations

- [zen:event-type:user.created](https://hookdeck.com/webhooks/zendesk/events/user#zen%3Aevent-type%3Auser.created): New user is added
- [zen:event-type:user.deleted](https://hookdeck.com/webhooks/zendesk/events/user#zen%3Aevent-type%3Auser.deleted): User is removed
- [zen:event-type:organization.created](https://hookdeck.com/webhooks/zendesk/events/organization#zen%3Aevent-type%3Aorganization.created): New organization is added
- [zen:event-type:organization.deleted](https://hookdeck.com/webhooks/zendesk/events/organization#zen%3Aevent-type%3Aorganization.deleted): Organization is removed

### Help center

- [zen:event-type:article.published](https://hookdeck.com/webhooks/zendesk/events/article#zen%3Aevent-type%3Aarticle.published): Help center article goes live
- [zen:event-type:article.unpublished](https://hookdeck.com/webhooks/zendesk/events/article#zen%3Aevent-type%3Aarticle.unpublished): Help center article is withdrawn

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [ticket](https://hookdeck.com/webhooks/zendesk/events/ticket) | 37 | 37 |
| [messaging_live_metrics](https://hookdeck.com/webhooks/zendesk/events/messaging-live-metrics) | 33 | 32 |
| [user](https://hookdeck.com/webhooks/zendesk/events/user) | 27 | 27 |
| [community_post](https://hookdeck.com/webhooks/zendesk/events/community-post) | 14 | 14 |
| [article](https://hookdeck.com/webhooks/zendesk/events/article) | 11 | 11 |
| [agent](https://hookdeck.com/webhooks/zendesk/events/agent) | 9 | 9 |
| [organization](https://hookdeck.com/webhooks/zendesk/events/organization) | 6 | 6 |
| [messaging](https://hookdeck.com/webhooks/zendesk/events/messaging) | 3 | 3 |

1 more resource. [All 142 events](https://hookdeck.com/webhooks/zendesk/events)

## In this hub

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

Not affiliated with Zendesk. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/zendesk.json) · [Report a correction](https://hookdeck.com/contact)
