Webhooks

出站 Webhooks 让您在项目中发生事件时接收实时 HTTP POST 通知。

概览

每当项目中发生特定事件时，Webhooks 会向您配置的任何 HTTPS 端点发送 JSON 载荷。每个 Webhook 可以订阅以下一个或多个事件：

Webhooks 以单个项目为范围。每个项目都有自己的 Webhook 端点集合，具有独立 的配置和签名密钥。

配置 Webhook

1. 转到项目的集成页面
2. 滚动到出站 Webhooks部分
3. 点击添加 Webhook
4. 输入端点 URL（生产环境中必须是 HTTPS）
5. 选择要订阅的事件
6. 点击保存

保存后，会显示一次签名密钥。请立即复制 — 之后无法再获取。您可以随时 从 Webhook 的操作菜单中重新生成它。

验证 Webhook 签名

每次 Webhook 投递都包含一个 X-SupDesk-Signature 头，其中包含请求体的 HMAC-SHA256 签名。要验证 Webhook：

1. 计算 HMAC-SHA256(您的签名密钥, 请求体原始数据)
2. 将结果与 X-SupDesk-Signature 头中的十六进制值进行比较 （在 sha256= 前缀之后）
3. 使用恒定时间比较以防止时序攻击

Node.js

import { createHmac, timingSafeEqual } from "crypto";
 
function verifyWebhook(secret, body, signature) {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  const sig = signature.replace("sha256=", "");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Python

import hmac
import hashlib
 
def verify_webhook(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    sig = signature.removeprefix("sha256=")
    return hmac.compare_digest(expected, sig)

Ruby

require "openssl"
 
def verify_webhook(secret, body, signature)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  sig = signature.sub("sha256=", "")
  Rack::Utils.secure_compare(expected, sig)
end

测试 Webhook

点击 Webhook 旁边的测试按钮，向其端点发送示例载荷。测试载荷包含 "event": "test" 和 data.message 字段。使用 webhook.site  等工具来检查投递的请求。

投递日志

投递日志显示每个 Webhook 最近 50 次投递尝试，包括：

• 事件 — 投递了哪个事件
• 状态 — success 或 failed
• 响应代码 — 端点返回的 HTTP 状态码
• 尝试次数 — 投递尝试次数（包括重试）
• 时间 — 投递尝试的时间

重试行为

当 Webhook 投递失败时（5xx 响应或网络超时），SupDesk 会以指数退避方式 重试最多 3 次：

客户端错误（4xx）不会重试 — 它们表示端点配置存在永久性问题。

方案要求

出站 Webhooks 在 Pro 和 Team 方案中可用。