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

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

Send timestamp
X-Zendesk-Webhook-Signature-Timestamp
What to build
Recompute a base64 HMAC-SHA256 over the timestamp header and raw body, and compare
Key
shared secret

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 ↗

Code

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`);
  });
}
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/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)

From hookdeck/webhook-skills ↗

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

Let Event Gateway verify Zendesk signatures.

Event Gateway verifies the signature on each Zendesk delivery before it reaches your service, then queues it and retries failures on your schedule.

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