โครงสร้างข้อมูลที่ถูกส่ง (Payload Format)

เมื่อตั้งค่า Endpoint ใน Dashboard สำเร็จ ตราบใดที่มีเหตุการณ์ (Event) เกิดขึ้นในฝั่ง RawPush ที่ตรงกับที่คุณ subscribe ไว้ ข้อมูลจะถูกส่ง POST เข้าหา Server คุณแบบ real-time ผ่าน HTTP Body เสมอ

🗃️ 1. รูปแบบ JSON มาตรฐาน

โครงสร้างข้อมูล (Payload) จะแนบข้อมูลบริบทรอบตัว เพื่อให้ Backend ของคุณนำไปประมวลผลได้ง่ายขึ้น

ตัวอย่าง req.body (JSON) — message.published event:

{
  "id": "wh_01HRXE8F...",
  "type": "event",
  "event": "message.published",
  "project_id": "prj_d93k2...",
  "timestamp": 1718000555,
  "payload": {
    "channel": "updates:feed_1",
    "event": "new_item",
    "data": {
       "item_id": "itm_49921",
       "action": "created"
    },
    "sender": {
      "session_id": "conn_01HGW...",
      "user_id": "usr_4922"
    }
  }
}

ตัวอย่าง — channel.occupied event:

{
  "id": "wh_01HRXE9G...",
  "type": "event",
  "event": "channel.occupied",
  "project_id": "prj_d93k2...",
  "timestamp": 1718000600,
  "payload": {
    "channel": "ticker:btc_usd",
    "sender": {
      "session_id": "system"
    }
  }
}

ตัวอย่าง — connection.auth_failed event:

{
  "id": "wh_01HRXEAG...",
  "type": "event",
  "event": "connection.auth_failed",
  "project_id": "prj_d93k2...",
  "timestamp": 1718000700,
  "payload": {
    "sender": {
      "session_id": "conn_01HGZ..."
    }
  }
}

Field Reference

Field	คำอธิบาย
id	รหัสอ้างอิงของ Webhook ฉบับนี้ (wh_...) ใช้ป้องกันการแจ้งเตือนซ้ำ (Deduplication)
type	ค่าคงที่ "event"
event	ชื่อ event ที่เกิดขึ้น (เช่น message.published, channel.occupied)
project_id	Project ID เพื่อแยกระบบ (กรณีมีหลายโปรเจกต์ส่งมารวมที่ API เดียว)
timestamp	Unix milliseconds ที่เกิดเหตุการณ์
payload.channel	ชื่อ channel ที่เกี่ยวข้อง (ถ้ามี)
payload.event	ชื่อ event ที่ client publish (เฉพาะ message.published)
payload.data	ข้อมูลที่ client แนบมา (เฉพาะ message.published, client_event)
payload.sender	ข้อมูลผู้ส่ง: session_id, user_id (หรือ "system" สำหรับ platform events)

🤔 2. การตอบรับ (Acknowledgment)

กฎข้อแรกของ Webhooks ทุกค่ายรวมถึง RawPush คือ... "เมื่อรับ request (POST) แล้ว ต้อง respond กลับทันที!"

RawPush จะคาดหวังว่า Backend ของคุณจะตอบกลับ HTTP 200 OK (หรือ 201, 204 ในกลุ่มพยัญชนะความสำเร็จ 2xx) ทันทีที่รับ JSON ชิ้นนี้เข้าไป

กฏของเรา:

• ทศนิยมความเร็ว (Fast Ack): อย่าทิ้งไว้ให้ระบบ RawPush รอการประมวลผลนานเกิน 3-5 วินาที ควรกดรับปุ๊บ res.send(200) ปั๊บ แล้วค่อยนำ Payload ใน Memory โยนต่อเข้า Background Job Queue ลึกๆ ของ Backend คุณ
• การตีคืน (Retries): หากระบบ Backend คุณล่มอยู่ หรือบังเอิญตอบเราด้วย 500, 502, 504 (Server Error) ... ระบบ RawPush จะตีความว่า "ส่งไม่ถึง" และจะ รอยิงซ้ำ (Retry with Exponential Backoff) ให้คุณจนกว่าจะสำเร็จ

⛔️ ความรับผิดชอบของ 4xx Error (Client Error)

ถ้าระบบของคุณบังเอิญตอบเราว่า 400 Bad Request หรือ 404 Not Found (เช่น คุณพิมพ์ URL ตอนตั้ง Webhook ผิดตัวอักษร) RawPush จะ ไม่ส่งซ้ำ ให้อีก เพราะเราถือว่า "ไม่ใช่จดหมายไปไม่ถึง แต่มันไม่มีผู้รับอยู่ตรงนั้นตั้งแต่แรก หรือไม่ก็ฝั่งนายพิมพ์โค้ดผิด"

ในบทถัดไป เราจะมาถึงแก่นแท้ของระบบความปลอดภัย -- การ verify signature จาก Headers ว่า POST request ที่เข้ามานั้นมาจาก RawPush จริงๆ เท่านั้น!