Webhook

イベントカタログ

どのイベントに参加できるかを API に問い合わせてください。このカタログは、ライブ オートメーション トリガーの信頼できる情報源から派生しているため、今日実際に発生したイベントのみをライフサイクル ステージ (獲得、エンゲージメント、ロイヤリティ、保持、コマース、擁護) ごとにグループ化し、それぞれにイベント キー、説明、サンプル ペイロードとともにリストします。応答には、共有ペイロード エンベロープと署名ヘッダーも文書化されています。

curl https://flash.socialhub.ai/api/v2/events/catalog \
  -H "Authorization: Bearer fl_live_..."

# { "data": { "events": [
#     { "event": "member.created", "label": "Member created",
#       "stage": "acquisition", "examplePayload": { ... } },
#     { "event": "loyalty.tier_upgraded", "label": "Tier upgraded",
#       "stage": "loyalty", "examplePayload": { ... } },
#     ...
#   ],
#   "payload": { "schema": { ... }, "headers": { ... } }
# } }

サブスクライブするときに、イベントの event キーを eventTypes 配列に直接入れます。 webhooks:manage スコープが必要です。

すべての署名を検証する

Flash は、標準 Webhook (HMAC-SHA256) を使用して、エンドポイントの whsec_ シークレットで各配信に署名します。 {webhook-id}.{webhook-timestamp}.{body} で署名を再計算し、定数時間で webhook-signature ヘッダーと比較します。一致しないものはすべて拒否し、リプレイに対して防御するには古すぎる webhook-timestamp を拒否します。署名キーは、仕様に従って、whsec_ プレフィックスの後のシークレットの Base64 デコードされたバイトです。シークレットのローテーション中、ヘッダーにはスペースで区切られた複数の v1,… 値が含まれます。いずれか が一致する場合に配信を受け入れます。

import crypto from "node:crypto";

// req.body must be the RAW, unparsed request body string.
function verifyFlashWebhook(headers, rawBody, whsec) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  const sigHeader = headers["webhook-signature"]; // "v1,<b64> v1,<b64> ..."

  // reject stale deliveries (5 min tolerance)
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const key = Buffer.from(whsec.replace(/^whsec_/, ""), "base64");
  const expected = crypto
    .createHmac("sha256", key)
    .update(`${id}.${ts}.${rawBody}`)
    .digest("base64");

  return sigHeader
    .split(" ")
    .map((p) => p.split(",")[1])
    .some((sig) =>
      sig &&
      sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)),
    );
}