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 array 中。需要 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)),
    );
}