# Verify Zendesk webhooks

Zendesk signs each webhook request so you can confirm it came from Zendesk and wasn't changed. `X-Zendesk-Webhook-Signature` holds a base64 HMAC-SHA256, keyed with the webhook's signing secret, over the `X-Zendesk-Webhook-Signature-Timestamp` value followed directly by the raw body. Event and trigger webhooks carry the same headers, so the same check works for a fixed JSON body, a body you defined or an empty one. Zendesk's docs give a Node example and name no verification library.

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)

## The 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/) |
| Send timestamp | `X-Zendesk-Webhook-Signature-Timestamp` | [Zendesk docs](https://developer.zendesk.com/documentation/webhooks/verifying/) |
| What to build | `Recompute a base64 HMAC-SHA256 over the timestamp header and raw body, and compare` | [Zendesk docs](https://developer.zendesk.com/documentation/webhooks/verifying/) |
| Key | `shared secret` | [Zendesk docs](https://developer.zendesk.com/documentation/webhooks/verifying/) |

## Zendesk webhook secret

Each webhook has its own signing secret, generated when the webhook is created. It's separate from the API key, basic or bearer authentication you can add to a webhook's requests. Keep it in an environment variable, not in source code.

- Reveal it on the webhook's details page in Admin Center with "Reveal secret", or call `GET /api/v2/webhooks/{webhook_id}/signing_secret`.
- There's one secret per webhook, and it doesn't exist until the webhook is fully created.
- While testing a webhook you haven't created yet, requests are signed with the static secret `dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==`. Testing an existing webhook uses that webhook's real secret, so don't leave the static one in production.
- Use the secret as the string Zendesk shows. Don't base64-decode it.
- Reset it with `POST /api/v2/webhooks/{webhook_id}/signing_secret`. New requests use the new secret from then on, and Zendesk describes no overlap period, so update your server straight away.
- An app that needs a webhook can define a 16 to 64 character alphanumeric secret in its requirements. Admins can't view or reset that secret.
- Zendesk's docs describe no test and live split beyond the static test secret.

Source: [Zendesk docs](https://developer.zendesk.com/documentation/webhooks/verifying/)

## Code

### Express

From [webhook-skills: skills/zendesk-webhooks/examples/express/src/index.js](https://github.com/hookdeck/webhook-skills/blob/9b7c561086c41940e310ef131b09928c1e7508b4/skills/zendesk-webhooks/examples/express/src/index.js)

```javascript
// Generated with: zendesk-webhooks skill
// https://github.com/hookdeck/webhook-skills
require('dotenv').config();
const express = require('express');
const crypto = require('crypto');

const app = express();

/**
 * Verify a Zendesk webhook signature.
 *
 * Zendesk signs: base64(HMAC_SHA256(secret, timestamp + rawBody)) — the
 * timestamp is prepended directly to the raw body with no separator.
 *
 * @param {Buffer} rawBody - Raw request body (Buffer from express.raw)
 * @param {string} signature - X-Zendesk-Webhook-Signature header value (base64)
 * @param {string} timestamp - X-Zendesk-Webhook-Signature-Timestamp header value
 * @param {string} secret - The webhook's signing secret
 * @returns {boolean} - Whether the signature is valid
 */
function verifyZendeskWebhook(rawBody, signature, timestamp, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(timestamp);              // timestamp first...
  hmac.update(rawBody);                // ...then the raw body, no separator
  const expected = hmac.digest('base64');

  try {
    return crypto.timingSafeEqual(
      Buffer.from(expected),
      Buffer.from(signature)
    );
  } catch {
    return false;                      // different lengths = invalid
  }
}

// Zendesk webhook endpoint - must use raw body for signature verification
app.post('/webhooks/zendesk',
  express.raw({ type: '*/*' }),
  async (req, res) => {
    const signature = req.headers['x-zendesk-webhook-signature'];
    const timestamp = req.headers['x-zendesk-webhook-signature-timestamp'];

    // Both headers are required
    if (!signature || !timestamp) {
      return res.status(400).send('Missing signature headers');
    }

    // Some requests (GET/DELETE) have no body - treat as empty
    const rawBody = req.body && req.body.length ? req.body : Buffer.alloc(0);

    // Verify webhook signature before trusting anything in the payload
    if (!verifyZendeskWebhook(rawBody, signature, timestamp, process.env.ZENDESK_WEBHOOK_SECRET)) {
      console.error('Webhook signature verification failed');
      return res.status(400).send('Invalid signature');
    }

    // Parse the payload after verification. Empty body = no event to dispatch.
    const payload = rawBody.length ? JSON.parse(rawBody.toString()) : {};

    // Event subscriptions carry a CloudEvents-style `type` field.
    // Webhooks connected to a trigger/automation send custom JSON (no `type`).
    const eventType = payload.type;
    console.log(`Received Zendesk webhook: ${eventType || '(custom trigger payload)'}`);

    switch (eventType) {
      case 'zen:event-type:ticket.created':
        console.log('Ticket created:', payload.detail?.id);
        // Your code: Sync ticket to CRM, alert on-call, etc.
        break;

      case 'zen:event-type:ticket.status_changed':
        console.log('Ticket status changed:', payload.detail?.id);
        // Your code: Update dashboards, SLA tracking, etc.
        break;

      case 'zen:event-type:ticket.comment_added':
        console.log('Ticket comment added:', payload.detail?.id);
        // Your code: Mirror comment to chat, notify watchers, etc.
        break;

      case 'zen:event-type:ticket.priority_changed':
        console.log('Ticket priority changed:', payload.detail?.id);
        // Your code: Escalation routing, etc.
        break;

      case 'zen:event-type:ticket.agent_assignment_changed':
        console.log('Ticket assignee changed:', payload.detail?.id);
        // Your code: Notify the newly assigned agent, etc.
        break;

      case 'zen:event-type:user.created':
        console.log('User created:', payload.detail?.id);
        // Your code: Provision account, send welcome flow, etc.
        break;

      case 'zen:event-type:organization.created':
        console.log('Organization created:', payload.detail?.id);
        // Your code: Sync organization to billing/CRM, etc.
        break;

      default:
        // Either an event type you haven't subscribed to handle, or a custom
        // trigger/automation payload without a `type` field.
        console.log('Unhandled Zendesk webhook payload');
    }

    // Return 200 to acknowledge receipt
    res.status(200).send('OK');
  }
);

// Health check endpoint
app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

// Export app for testing
module.exports = { app, verifyZendeskWebhook };

// Start server only when run directly (not when imported for testing)
if (require.main === module) {
  const PORT = process.env.PORT || 3000;
  app.listen(PORT, () => {
    console.log(`Server running on http://localhost:${PORT}`);
    console.log(`Webhook endpoint: POST http://localhost:${PORT}/webhooks/zendesk`);
  });
}
```

### Next.js

From [webhook-skills: skills/zendesk-webhooks/examples/nextjs/app/webhooks/zendesk/route.ts](https://github.com/hookdeck/webhook-skills/blob/9b7c561086c41940e310ef131b09928c1e7508b4/skills/zendesk-webhooks/examples/nextjs/app/webhooks/zendesk/route.ts)

```typescript
// Generated with: zendesk-webhooks skill
// https://github.com/hookdeck/webhook-skills
import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';

/**
 * Verify a Zendesk webhook signature.
 *
 * Zendesk signs: base64(HMAC_SHA256(secret, timestamp + rawBody)) — the
 * timestamp is prepended directly to the raw body with no separator.
 */
function verifyZendeskWebhook(
  rawBody: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(timestamp); // timestamp first...
  hmac.update(rawBody); //    ...then the raw body, no separator
  const expected = hmac.digest('base64');

  try {
    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
  } catch {
    return false; // different lengths = invalid
  }
}

export async function POST(request: NextRequest) {
  // Read the raw body BEFORE parsing so the signature matches exactly
  const rawBody = await request.text();
  const signature = request.headers.get('x-zendesk-webhook-signature');
  const timestamp = request.headers.get('x-zendesk-webhook-signature-timestamp');

  // Both headers are required
  if (!signature || !timestamp) {
    return NextResponse.json({ error: 'Missing signature headers' }, { status: 400 });
  }

  // Verify webhook signature before trusting anything in the payload
  if (!verifyZendeskWebhook(rawBody, signature, timestamp, process.env.ZENDESK_WEBHOOK_SECRET!)) {
    console.error('Webhook signature verification failed');
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
  }

  // Parse the payload after verification. Empty body = no event to dispatch.
  const payload = rawBody.length ? JSON.parse(rawBody) : {};

  // Event subscriptions carry a CloudEvents-style `type` field.
  // Webhooks connected to a trigger/automation send custom JSON (no `type`).
  const eventType: string | undefined = payload.type;
  console.log(`Received Zendesk webhook: ${eventType || '(custom trigger payload)'}`);

  switch (eventType) {
    case 'zen:event-type:ticket.created':
      console.log('Ticket created:', payload.detail?.id);
      // Your code: Sync ticket to CRM, alert on-call, etc.
      break;

    case 'zen:event-type:ticket.status_changed':
      console.log('Ticket status changed:', payload.detail?.id);
      // Your code: Update dashboards, SLA tracking, etc.
      break;

    case 'zen:event-type:ticket.comment_added':
      console.log('Ticket comment added:', payload.detail?.id);
      // Your code: Mirror comment to chat, notify watchers, etc.
      break;

    case 'zen:event-type:ticket.priority_changed':
      console.log('Ticket priority changed:', payload.detail?.id);
      // Your code: Escalation routing, etc.
      break;

    case 'zen:event-type:ticket.agent_assignment_changed':
      console.log('Ticket assignee changed:', payload.detail?.id);
      // Your code: Notify the newly assigned agent, etc.
      break;

    case 'zen:event-type:user.created':
      console.log('User created:', payload.detail?.id);
      // Your code: Provision account, send welcome flow, etc.
      break;

    case 'zen:event-type:organization.created':
      console.log('Organization created:', payload.detail?.id);
      // Your code: Sync organization to billing/CRM, etc.
      break;

    default:
      // Either an event type you haven't subscribed to handle, or a custom
      // trigger/automation payload without a `type` field.
      console.log('Unhandled Zendesk webhook payload');
  }

  // Return 200 to acknowledge receipt
  return NextResponse.json({ received: true });
}
```

### FastAPI

From [webhook-skills: skills/zendesk-webhooks/examples/fastapi/main.py](https://github.com/hookdeck/webhook-skills/blob/9b7c561086c41940e310ef131b09928c1e7508b4/skills/zendesk-webhooks/examples/fastapi/main.py)

```python
# Generated with: zendesk-webhooks skill
# https://github.com/hookdeck/webhook-skills
import os
import hmac
import hashlib
import base64
import json

from dotenv import load_dotenv
from fastapi import FastAPI, Request, HTTPException

load_dotenv()

app = FastAPI()

zendesk_secret = os.environ.get("ZENDESK_WEBHOOK_SECRET")


def verify_zendesk_webhook(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    """Verify a Zendesk webhook signature.

    Zendesk signs base64(HMAC_SHA256(secret, timestamp + raw_body)) — the
    timestamp is prepended directly to the raw body with no separator.
    """
    message = timestamp.encode("utf-8") + raw_body  # timestamp first, then body
    expected = base64.b64encode(
        hmac.new(secret.encode("utf-8"), message, hashlib.sha256).digest()
    ).decode("utf-8")
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/zendesk")
async def zendesk_webhook(request: Request):
    # Read the raw body BEFORE parsing so the signature matches exactly
    raw_body = await request.body()
    signature = request.headers.get("x-zendesk-webhook-signature")
    timestamp = request.headers.get("x-zendesk-webhook-signature-timestamp")

    # Both headers are required
    if not signature or not timestamp:
        raise HTTPException(status_code=400, detail="Missing signature headers")

    # Verify webhook signature before trusting anything in the payload
    if not verify_zendesk_webhook(raw_body, signature, timestamp, zendesk_secret):
        raise HTTPException(status_code=400, detail="Invalid signature")

    # Parse the payload after verification. Empty body = no event to dispatch.
    payload = json.loads(raw_body) if raw_body else {}

    # Event subscriptions carry a CloudEvents-style `type` field.
    # Webhooks connected to a trigger/automation send custom JSON (no `type`).
    event_type = payload.get("type")
    detail = payload.get("detail", {})
    print(f"Received Zendesk webhook: {event_type or '(custom trigger payload)'}")

    if event_type == "zen:event-type:ticket.created":
        print(f"Ticket created: {detail.get('id')}")
        # Your code: Sync ticket to CRM, alert on-call, etc.

    elif event_type == "zen:event-type:ticket.status_changed":
        print(f"Ticket status changed: {detail.get('id')}")
        # Your code: Update dashboards, SLA tracking, etc.

    elif event_type == "zen:event-type:ticket.comment_added":
        print(f"Ticket comment added: {detail.get('id')}")
        # Your code: Mirror comment to chat, notify watchers, etc.

    elif event_type == "zen:event-type:ticket.priority_changed":
        print(f"Ticket priority changed: {detail.get('id')}")
        # Your code: Escalation routing, etc.

    elif event_type == "zen:event-type:ticket.agent_assignment_changed":
        print(f"Ticket assignee changed: {detail.get('id')}")
        # Your code: Notify the newly assigned agent, etc.

    elif event_type == "zen:event-type:user.created":
        print(f"User created: {detail.get('id')}")
        # Your code: Provision account, send welcome flow, etc.

    elif event_type == "zen:event-type:organization.created":
        print(f"Organization created: {detail.get('id')}")
        # Your code: Sync organization to billing/CRM, etc.

    else:
        # Either an event type you haven't subscribed to handle, or a custom
        # trigger/automation payload without a `type` field.
        print("Unhandled Zendesk webhook payload")

    # Return 200 to acknowledge receipt
    return {"received": True}


@app.get("/health")
async def health():
    return {"status": "ok"}


if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8000)
```

Or install the Zendesk webhooks skill: `npx skills add hookdeck/webhook-skills --skill zendesk-webhooks`

## Common failures

- **Body parsed before verification.** Sign the body as it arrived. Re-serializing parsed JSON or XML can change the bytes and break the match.
- **Timestamp changed or left out.** `X-Zendesk-Webhook-Signature-Timestamp` is an ISO 8601 string, not Unix seconds. Put it in front of the body exactly as sent, with no separator.
- **Wrong secret.** The static test secret only applies while you test a webhook that doesn't exist yet. Each created webhook has its own secret, and you use it as the string Zendesk shows, without base64-decoding it.
- **No body on the request.** A trigger webhook using GET or DELETE has no body, and neither does one using another method with a form-encoded format. Sign the timestamp alone, and make sure a missing body doesn't become the text `undefined` or `null`.

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

---

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)
