เว็บฮุค
สมัครใช้งานระบบของคุณเองสำหรับเหตุการณ์ Flash ลงทะเบียนเอนด์พอยต์ HTTPS สำหรับเหตุการณ์ที่คุณสนใจ และ Flash จะส่งเพย์โหลดขนาดเล็กที่ลงนามแล้วในทันทีที่แต่ละเหตุการณ์ทำงาน — ไม่ต้องทำการสำรวจ ไม่ต้องส่งออกรายวัน ลายเซ็นเป็นไปตามข้อกำหนด Standard Webhooks การส่งจะลองใหม่ด้วยการหน่วงเวลา และทุกครั้งที่พยายามจะถูกบันทึกไว้
ลงทะเบียนปลายทาง
สร้างเอนด์พอยต์ webhook ด้วยคีย์ Bearer fl_live_ ที่เก็บขอบเขต webhooks:manage โพสต์ HTTPS url และรายการ eventTypes ที่คุณต้องการส่งไปที่นั่น รหัสลับการลงนาม ในการตอบกลับและจะไม่ถูกส่งกลับมาอีก — เก็บรักษาไว้ให้ปลอดภัย คุณจำเป็นต้องใช้มันเพื่อตรวจสอบการส่งทุกครั้ง
curl -X POST https://flash.socialhub.ai/api/v2/webhooks \
-H "Authorization: Bearer fl_live_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.your-app.com/flash",
"description": "prod ingest",
"eventTypes": ["member.created", "loyalty.tier_upgraded"]
}'
# 201 Created
# {
# "data": {
# "id": "whe_...",
# "url": "https://hooks.your-app.com/flash",
# "eventTypes": ["member.created", "loyalty.tier_upgraded"],
# "status": "active",
# "secret": "whsec_..." <-- shown ONCE, store it now
# }
# }จัดการตำแหน่งข้อมูลในภายหลังด้วย GET /api/v2/webhooks (รายการ ไม่มีข้อมูลลับ), PATCH /api/v2/webhooks/{id} (เปลี่ยน url / เหตุการณ์ / สถานะ หรือส่ง { "action": "rotate_secret" } เพื่อม้วนข้อมูลลับ) และ DELETE /api/v2/webhooks/{id} คุณยังสามารถลงทะเบียน ทดสอบ ping และเล่นซ้ำการส่งได้จาก การตั้งค่า → Webhooks
แคตตาล็อกกิจกรรม
ถาม 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
เพย์โหลดขนาดเล็กที่ไม่ใช่ข้อมูลส่วนบุคคล (PII)
ทุกการส่งข้อมูลจะบรรจุอยู่ในซองขนาดเล็กเดียวกัน ประกอบด้วย id ที่เสถียร, type เหตุการณ์, created_at timestamp และ data บล็อกขนาดกะทัดรัด ข้อมูลที่ส่งมา จะไม่ประกอบด้วยข้อมูลส่วนบุคคล เช่น อีเมล ชื่อ เบอร์โทรศัพท์ หรือที่อยู่ เมื่อคุณต้องการรายละเอียดของสมาชิก ให้ดึงข้อมูลเหล่านั้นกลับมาผ่าน API ที่ได้รับการตรวจสอบสิทธิ์แล้วโดยใช้ member_ref วิธีนี้จะช่วยเก็บรักษาข้อมูลส่วนบุคคลไว้ในบันทึกของสมาชิกและไม่ปรากฏในบันทึกเว็บฮุคของคุณ
POST https://hooks.your-app.com/flash
webhook-id: evt_a1b2c3... # stable across retries — dedupe on this
webhook-timestamp: 1767225600 # unix seconds
webhook-signature: v1,K5x0mF...== # base64 HMAC-SHA256 (may be space-separated during rotation)
Content-Type: application/json
{
"id": "evt_a1b2c3...",
"type": "loyalty.tier_upgraded",
"created_at": "2026-01-01T00:00:00.000Z",
"data": {
"resource_id": "mbr_...",
"member_ref": "mbr_...", // opaque member id — fetch PII via the API
"tier": "Gold", // present on loyalty / tier events
"amount_band": "100-500" // coarse band on commerce events — never the exact amount
}
}ตรวจสอบทุกลายเซ็น
Flash ลงนามการจัดส่งแต่ละรายการด้วยความลับ whsec_ ปลายทางของคุณโดยใช้ Webhooks มาตรฐาน (HMAC-SHA256) คำนวณลายเซ็นใหม่บน {webhook-id}.{webhook-timestamp}.{body} และเปรียบเทียบกับส่วนหัว webhook-signature ในเวลาคงที่ ปฏิเสธสิ่งใดก็ตามที่ไม่ตรงกัน และปฏิเสธ webhook-timestamp ที่เก่าเกินไปที่จะป้องกันการเล่นซ้ำ คีย์การลงนามคือไบต์ที่ถอดรหัส base64 ของข้อมูลลับที่อยู่หลังคำนำหน้า whsec_ ตามข้อกำหนด ในระหว่างการหมุนเวียนข้อมูลลับ ส่วนหัวจะมีค่า 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)),
);
}ลองใหม่ idempotency และบันทึกการจัดส่ง
คืน 2xx อย่างรวดเร็ว
ยืนยันด้วย 2xx ใดๆ และทำงานของคุณแบบอะซิงโครนัส การเชื่อมต่อ 429, 5xx, การหมดเวลา หรือข้อผิดพลาดในการเชื่อมต่อ จะถูกพิจารณาว่าสามารถลองเชื่อมต่อใหม่ได้
ลองใหม่โดยอัตโนมัติพร้อมแบ็คออฟ
ความล้มเหลวที่ลองใหม่ได้จะถูกลองอีกครั้งโดยมีแบ็คออฟแบบเอ็กซ์โพเนนเชียลและกระวนกระวายใจเต็มรูปแบบ 3xx หรือ non-429 4xx ถือเป็นความล้มเหลวถาวรและไม่ได้ลองใหม่
ลบข้อมูลซ้ำซ้อนโดย webhook-id
id จะเหมือนกันทุกครั้งที่ลองใหม่ ดังนั้นอย่างน้อยหนึ่งครั้งในการจัดส่งจึงปลอดภัย: ให้ถือว่า webhook-id ที่ซ้ำกันได้รับการจัดการแล้ว
บันทึกการจัดส่งและเล่นซ้ำ
ทุกครั้งที่พยายามส่ง ระบบจะบันทึกข้อมูลไว้ หากจำนวนครั้งที่พยายามส่งซ้ำหมดลง การส่งจะถูกทำเครื่องหมายว่าล้มเหลว คุณสามารถตรวจสอบและเล่นซ้ำการส่งได้จาก การตั้งค่า → เว็บฮุค