Webhook

Webhook 让你把 AskAIs 智能客服系统 事件镜像到你自己的系统中 —— CRM、分析、Slack 以及任何使用 HTTP 通信的系统。

创建 webhook

前往 设置 → Webhooks → 新建 webhook。选择事件，粘贴你的 URL，保存。你会得到一个用于签名载荷的密钥。

事件类型

• conversation.created
• conversation.updated —— 状态、优先级、分配
• conversation.resolved
• message.created —— 任意消息，任意发送者
• contact.created
• contact.updated

载荷结构

POST https://your-app.com/webhooks/singlink
Content-Type: application/json
X-SingLink-Event: message.created
X-SingLink-Signature: sha256=ab12cd34...
X-SingLink-Timestamp: 1747300800

{
  "id": "evt_01HX...",
  "type": "message.created",
  "tenantId": "tnt_01HX...",
  "data": { /* event-specific payload */ }
}

验证签名

使用 webhook 密钥对 timestamp + "." + rawBody 计算 HMAC-SHA256。 将其与 X-SingLink-Signature 请求头进行比较（采用恒定时间比较）。

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(req, secret) {
  const ts = req.headers["x-singlink-timestamp"];
  const sig = req.headers["x-singlink-signature"];
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(ts + "." + req.rawBody)
    .digest("hex");
  return timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

重试

对于非 2xx 响应，我们会按指数退避重试：1s、10s、1m、10m、1h。重试 5 次后事件会被标记为失败；你可以在管理后台查看失败记录。

测试 ping

每个 webhook 都有一个 发送测试 按钮，它会发送一个虚拟的 webhook.ping 事件。可用于在正式上线前验证你的端点是否接受 签名。