What Are Zendesk Webhooks and How Do They Work? (2026)

A Zendesk webhook is a saved connection that makes Zendesk send an HTTPS request with a JSON payload to a URL you control the moment an event happens, either when a trigger or automation runs its "Notify active webhook" action or when a subscribed user, organization or Help Center event fires. It's how you get a Slack ping when a VIP files a ticket, a CRM record updated the second a customer's details change, or a custom alert on a specific tag. Every limit and header below was checked against Zendesk's developer documentation in September 2026.

What is a webhook, and how is it different from the API?

The cleanest way to understand a webhook is to contrast it with the API.

• The API is like checking the door. You walk over, open it, and look to see if anyone's there. To stay current you have to keep checking. That's polling, and it's the model behind most Zendesk API integrations.
• A webhook is the doorbell. You don't check anything. When someone arrives, the bell rings and you go answer it. The event comes to you.

In technical terms, a webhook is a user-defined HTTP callback. You give Zendesk an endpoint URL (a web address you control) and tell it which events you care about. When one of those events happens, Zendesk sends an outbound HTTP request with a JSON payload to your URL. Your server receives it and does whatever you've programmed: post to Slack, write to a database, kick off a workflow.

So the API and webhooks are two halves of a whole. The API is pull (request and response, you initiate). Webhooks are push (event-driven, Zendesk initiates). Real integrations usually use both: a webhook tells you something happened, and you call the API to fetch the full detail or write something back. Polling the API every few seconds to ask "any new urgent tickets yet?" burns rate limit for mostly empty answers, which is the cost webhooks remove.

How do Zendesk webhooks work?

In Zendesk, a webhook is a reusable connection object. It stores the destination URL, the HTTP method, the request format, the authentication, and any custom headers. On its own it does nothing; it has to be invoked. There are two ways to invoke one, and the choice you make at creation time decides what the webhook can do.

1. Connect it to a trigger or automation (the common path). This is how you react to ticket activity. You create the webhook with the subscription value conditional_ticket_events, then point a trigger or automation at it. The trigger decides when (its conditions, such as "priority is Urgent") and the webhook decides where (the endpoint). The trigger fires the webhook through the "Notify active webhook" action, where you also supply the request body it should send.

2. Subscribe it to Zendesk events directly. Instead of going through a trigger, the webhook subscribes to specific platform events, such as a change to a user, organization, article, community post or agent availability record. These event subscriptions fire automatically when the matching event occurs, with no business rule involved.

The docs are explicit that the two modes don't mix: a webhook subscribed to a Zendesk event can't connect to a trigger or automation. If you need both kinds of reaction, you build two webhooks.

You create and manage webhooks in Admin Center → Apps and integrations → Webhooks, or through the Webhooks API. Trial accounts can have at most 10. The API view makes the structure obvious. Here's a webhook built to be fired by a trigger, authenticated with a bearer token:

{
  "webhook": {
    "name": "Notify Slack of urgent tickets",
    "status": "active",
    "endpoint": "https://hooks.example.com/zendesk/urgent",
    "http_method": "POST",
    "request_format": "json",
    "subscriptions": ["conditional_ticket_events"],
    "authentication": {
      "type": "bearer_token",
      "add_position": "header",
      "data": { "token": "••••••••••••" }
    },
    "custom_headers": { "X-Source": "zendesk" }
  }
}

The required fields are the name, a status (active or inactive), the endpoint URL, the http_method, the request_format, and the subscriptions array. Event subscriptions must use POST and json; webhooks fired by triggers or automations can use POST, PUT or PATCH. You can attach up to five custom headers, with names up to 128 characters and values up to 1,000, and the endpoint should be HTTPS.

How do you fire a webhook from a trigger?

This is the pattern most teams actually use, so it's worth seeing end to end. Say you want a Slack message whenever an Urgent ticket comes in.

1. Create the webhook (as above) pointing at your Slack-receiving endpoint, with subscriptions: ["conditional_ticket_events"].
2. Create a trigger with a condition like Ticket → Priority → Is → Urgent.
3. Add the action "Notify active webhook," select your webhook, and write the JSON body to send. Zendesk placeholders inject live ticket data into that body.

The body you write on the trigger looks like this. The double-brace placeholders are replaced with the actual ticket's values when the trigger fires:

{
  "text": "Urgent ticket #{{ticket.id}}: {{ticket.title}}",
  "requester": "{{ticket.requester.name}}",
  "priority": "{{ticket.priority}}",
  "url": "{{ticket.link}}"
}

Now, the moment any ticket hits Urgent and the trigger's conditions match, Zendesk sends that JSON to your endpoint. The trigger owns the logic and the webhook owns the delivery. Because triggers run when a ticket is created or updated, this happens in real time, not on a schedule. Automations are the exception: they run hourly, so a webhook fired by an automation arrives on that cycle.

What does a webhook request look like on your end?

When the webhook fires, your server receives a standard HTTP request. Beyond your custom headers and the JSON body, Zendesk attaches a few headers of its own:

• x-zendesk-account-id: which Zendesk account sent it.
• x-zendesk-webhook-signature: the cryptographic signature (covered below).
• x-zendesk-webhook-signature-timestamp: when the request was signed.

For webhooks that subscribe to events, the JSON body follows a consistent envelope. A user event, for example, looks like this:

{
  "type": "zen:event-type:user.alias_changed",
  "account_id": 12514403,
  "id": "6b9bbadf-5725-4e92-bebe-7b71011bf5f1",
  "subject": "zen:user:6596848315901",
  "time": "2099-07-04T05:33:18Z",
  "zendesk_event_version": "2022-06-20",
  "detail": {
    "email": "[email protected]",
    "role": "end-user",
    "organization_id": "360000000001",
    "updated_at": "2099-07-04T05:33:18Z"
  }
}

The envelope is predictable: a type naming the event, the account_id, a unique id, the subject it concerns, a time, a versioned zendesk_event_version, and a detail object carrying the changed resource. For trigger-fired webhooks, the body is whatever you defined on the trigger. There's no fixed schema, because you write it.

Which authentication methods do Zendesk webhooks support?

When your endpoint needs to know the caller is allowed in, Zendesk offers three authentication methods on the webhook, plus the option of none (which Zendesk's docs say is not recommended):

Authentication is about your destination accepting the request. Proving the request truly came from Zendesk is a separate job, and that's what the signature is for.

How do you verify a Zendesk webhook signature?

Your endpoint is a public URL. Anyone who discovers it could POST fake payloads at it. So every Zendesk webhook request carries a digital signature you can check against a signing secret.

When you create a webhook, Zendesk generates a unique signing secret for it. On every request, Zendesk computes:

signature = base64( HMAC-SHA256( timestamp + body, signing_secret ) )

It sends that signature in the x-zendesk-webhook-signature header and the timestamp in x-zendesk-webhook-signature-timestamp. To verify, your server recomputes the same HMAC over the received timestamp plus the raw body using your copy of the secret, then compares. If they match, the request is authentic and untampered; if not, reject it. A minimal Node check:

const crypto = require("crypto");

function isFromZendesk(signature, timestamp, rawBody, secret) {
  const data = timestamp + rawBody;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(data)
    .digest("base64");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Two practical notes. Hash the raw request body, because re-serializing parsed JSON can change bytes and break the match. And while you're building a webhook, before it exists, Zendesk signs test requests with a fixed test secret, dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==, so you can validate your verification code before going live. Once created, the webhook gets its own secret. Treat that secret like any other credential and keep it out of source control.

What happens when a webhook fails? Retries and the circuit breaker

Networks fail, and your endpoint will occasionally be down or slow. Zendesk's retry rules decide whether a hiccup costs you an event:

• Timeouts. Zendesk waits 12 seconds for your endpoint to respond and retries up to 5 times on timeout. Your handler should return a 2xx quickly and do heavy work asynchronously.
• Conflicts. On an HTTP 409 it retries up to 3 times.
• Rate limits and outages. On a 429 or 503, Zendesk retries only if your response includes a retry-after header under 60 seconds. Without that header, the request isn't retried.
• Circuit breaker. If 70% of a webhook's requests error within five minutes, or it gets more than 1,000 error responses in five minutes, Zendesk trips a circuit breaker and stops sending for five seconds. A webhook with fewer than 100 requests in the window won't trip it, and a failed request after the pause restarts the five-second timer.
• Activity log. Each webhook keeps a 7-day log of its invocations, so you can see what fired, what came back, and what failed.

Zendesk does not deactivate a webhook automatically for consecutive failures, so a broken endpoint can fail quietly for days unless someone reads that log. For builders the rule is: respond fast, return accurate status codes, and make your handler idempotent, because a retry means the same event can legitimately arrive more than once.

When should you use webhooks, the API, or a native integration?

The three overlap, and the right one depends on the job:

• Webhooks fit when you need to react in real time to events and push data outward: alerts, syncs, custom workflows. Low overhead, but you host and secure the endpoint.
• The API fits when you need to pull data on demand or write back into Zendesk: fetch a ticket's history, bulk-update fields, run a report. Often a webhook fires first ("something changed"), then your code calls the API to act on it.
• Native or Marketplace integrations (the prebuilt Slack, Jira and Salesforce apps) fit when a maintained connector already does what you need, with no code and no endpoint to run, at the cost of flexibility.

A common pattern combines all three: a native app for the heavy lifting, a webhook for the one real-time event the app misses, and the API for the custom read and write in between.

Where does an AI agent fit alongside webhooks?

Keeping external systems in sync is the plumbing webhooks exist for, and it's also where an AI agent layer like Macha plugs in. Macha isn't a help desk and doesn't replace Zendesk; it runs on top of it. A Zendesk trigger with a custom webhook can hand a ticket to a Macha agent under conditions you set in Zendesk's admin, so only the tickets you want ever reach the agent. The agent reads the ticket and its custom fields, looks things up in connected systems, drafts a reply or internal note, sets fields and adds tags. Macha's docs recommend one guard: have the trigger add a unique tag when it fires and exclude that tag in its conditions, or the agent's own update re-fires the trigger in a loop.

On cost, Macha bills per ticket: one thread with one person, charged once however many steps it takes, whether that's classifying, looking up an order, drafting a reply or closing it out. Pricing starts at $299 a month for 750 tickets, about $0.40 each, and setup and monitoring by the Macha team are included. A vendor that bills per resolution earns more when its definition of "resolved" is generous; a per-ticket charge doesn't depend on that definition. If you'd rather wire up your own webhooks, that path stays open; if the orchestration is the part you don't want to build and maintain, that's the gap an agent layer fills. We walk through it in how to automate Zendesk with AI, and the trial gives you $50 of free usage with no credit card.

Frequently asked questions

What is a Zendesk webhook? A webhook is a connection Zendesk uses to push data to an external URL the moment an event happens, the inverse of the API, which you pull data from. You give Zendesk an endpoint, and when a matching event occurs (a ticket meets a trigger's conditions, or a user or organization record changes), Zendesk sends an HTTP request with a JSON payload to that URL so your system can react in real time.

How do you trigger a Zendesk webhook? For ticket activity, create the webhook with the conditional_ticket_events subscription, then build a trigger (or automation) whose conditions decide when it fires. Add the "Notify active webhook" action, select your webhook, and write the JSON body, using placeholders such as ticket.id in double braces to inject live ticket data. For non-ticket activity, a webhook can instead subscribe directly to platform events (user, organization, article and more).

What authentication do Zendesk webhooks support? Three methods on the outbound request: API key (a name/value header), basic auth (username and password), and bearer token. You can also send with no authentication, which Zendesk doesn't recommend. These authenticate the request to your endpoint. Verifying the request came from Zendesk is done separately, with the signature.

How do I verify a Zendesk webhook is genuine? Each webhook has a unique signing secret. On every request Zendesk sends base64(HMAC-SHA256(timestamp + body)) in the x-zendesk-webhook-signature header, with the timestamp in x-zendesk-webhook-signature-timestamp. Recompute the same HMAC over the received timestamp plus the raw body using your copy of the secret and compare. A match means the request is authentic and untampered.

Does Zendesk retry a failed webhook? Yes. Zendesk waits 12 seconds for a response and retries up to 5 times on timeout, up to 3 times on an HTTP 409, and on a 429 or 503 only when your retry-after header is under 60 seconds. A circuit breaker pauses a webhook for five seconds when 70% of its requests error, or it gets more than 1,000 errors, within five minutes. Each webhook keeps a 7-day activity log. Because retries can deliver the same event twice, make your handler idempotent.

What's the difference between webhooks and the Zendesk API? The API is pull: your code requests data or writes changes when you decide. Webhooks are push: Zendesk sends data to you automatically when an event fires. Most integrations use both. A webhook says "something happened," then your code calls the API to fetch detail or write back.

How many webhooks can a Zendesk account have? Zendesk's API reference states that trial accounts are limited to 10 webhooks. It doesn't publish a cap for paid plans on that page, so check your own Admin Center if you plan to run many.

What should you set up first?

Start with one trigger-fired webhook for the event you most need in real time, verify its HMAC signature with the test secret before you go live, and read its 7-day activity log after the first day to catch timeouts. Pair it with the API for reads and writes. For how triggers, automations and webhooks fit together with the rest of Zendesk's rules, see Zendesk business rules explained.

Webhook mechanics verified against Zendesk's developer documentation, September 2026. Zendesk updates its platform periodically, so confirm endpoints, limits and headers in your own account before relying on them.