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 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
{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_event_version in the body Seen: 2022-06-20, 2022-11-06, 2022-12-06.
x-zendesk-account-id, x-zendesk-webhook-id, x-zendesk-webhook-invocation-id, x-zendesk-webhook-signature-timestamp 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 setssubscriptionstoconditional_ticket_events, and you define its content in the trigger or automation'snotification_webhookaction. - 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}/invocationslists the last 7 days of invocations, and each invocation's attempts are available under it.
Delivery behaviour
12 seconds a request that times out is retried up to five times Retries some failures 409 up to three times, timeouts up to five, and 429 or 503 with a retry-after under 60 seconds After retries no resend the activity log keeps 7 days of invocations, and Zendesk describes no replay Ordering not guaranteed webhook jobs run independently, so compare time Known failure modes
From Hookdeck's Zendesk guide →-
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 → -
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
Handle duplicates →idfor event webhooks, and on a key you add to the payload for trigger webhooks. -
A 500 isn't retried
Zendesk lists retries for a 409, for a 429 or 503 with a
Retries and lost events →retry-afterunder 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. -
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
Retries and lost events →circuit broken, and those events may never be delivered.
Zendesk webhook best practices
- Verify the signature over the raw body. 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. Zendesk retries a timed-out request up to five times, so queue the work and respond first.
- Deduplicate on your own key.
Record the body's
idon event webhooks, and add a key to the payload you write for a trigger or automation. - Don't rely on arrival order.
Webhook jobs run independently. Compare
timefor eachsubject, or fetch the current record. - Ask for a retry when you can't accept a request.
A 503 with a
retry-afterunder 60 seconds is retried, while Zendesk lists no retry for a plain 500. - Check the invocation log yourself.
Zendesk's docs describe no failure alerts, so poll failed and
circuit brokeninvocations within the 7 days it keeps them.
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 | 37 | 37 |
messaging_live_metrics | 33 | 32 |
user | 27 | 27 |
community_post | 14 | 14 |
article | 11 | 11 |
agent | 9 | 9 |
organization | 6 | 6 |
messaging | 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.