用途:该技能用于搭建和调试 Zendesk Webhook 处理器,涵盖签名校验、事件订阅与触发器/自动化两种 Webhook 模式,以及工单、用户、组织等事件处理。
主要能力:Zendesk 对每个 Webhook 使用 HMAC-SHA256 并以 base64 编码签名,签名消息为时间戳直接拼接原始请求体,无分隔符:base64(HMAC_SHA256(timestamp + body))。Zendesk 不遵循 Standard Webhooks 规范,也没有官方校验 SDK,需用语言自身的加密原语手动校验。请求带两个头:X-Zendesk-Webhook-Signature(base64 签名)与 X-Zendesk-Webhook-Signature-Timestamp(拼接在请求体前的时间戳)。必须使用原始请求体,不能先 JSON.parse。部分请求(如 Webhook 上的 GET/DELETE)没有请求体,需处理空体情况。示例代码展示了用 Node.js crypto 计算 HMAC 并做 timingSafeEqual 比较。签名密钥来自 GET /api/v2/webhooks/{webhook_id}/signing_secret,或在 Admin Center 的 Webhook 中显示密钥;创建前的测试 Webhook 固定使用静态密钥 dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==。
使用方式:Webhook 有两种互斥模式——事件订阅(订阅 zen:event-type:* 事件,Zendesk 发送带 type 字段的 CloudEvents 风格信封)与连接到触发器/自动化(请求体是自定义 JSON,无 type 字段)。同一 Webhook 不能同时订阅事件又连接触发器,但两种模式的签名校验相同。常见事件类型包括 ticket.created、ticket.status_changed、ticket.comment_added、ticket.priority_changed、ticket.agent_assignment_changed、user.created、organization.created。
适用场景:设置 Zendesk Webhook 处理器、排查签名校验失败、理解事件订阅与触发器 Webhook 的区别、处理工单/用户/组织事件。本地开发可用 npx hookdeck-cli listen 3000 zendesk --path /webhooks/zendesk 启动隧道。完整处理器示例参见 examples/express、examples/nextjs、examples/fastapi。建议配合 webhook-handler-patterns 技能处理幂等、错误与重试。
限制:资料中未提供具体的收费、平台或效果说明;环境变量 ZENDESK_WEBHOOK_SECRET 需填写签名密钥。