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 事件。可用於在正式上線前驗證你的端點是否接受 簽章。