Webhook

Webhook を使うと、AskAIs Customer Service のイベントを自分のシステムに反映できます — 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 イベントを送信します。本番稼働前にエンドポイントが 署名を受け入れることを確認するのに便利です。