웹훅

이벤트 카탈로그

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는 표준 웹훅(HMAC-SHA256)을 사용하여 엔드포인트의 whsec_ 비밀 키로 각 ​​전송에 서명합니다. {webhook-id}.{webhook-timestamp}.{body}에 대한 서명을 다시 계산하고 상수 시간 내에 webhook-signature 헤더와 비교합니다. 일치하지 않는 모든 항목을 거부하고, 재전송 공격에 대응하기에는 너무 오래된 webhook-timestamp도 거부합니다. 서명 키는 사양에 따라 whsec_ 접두사 뒤에 오는 비밀 키의 base64 디코딩된 바이트입니다. 비밀 키 순환 시 헤더에는 공백으로 구분된 여러 개의 v1,… 값이 포함됩니다. any가 일치하면 전달을 수락하세요.

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)),
    );
}