เอกสารอ้างอิง Webhook

สรุป

ลงทะเบียนเอนด์พอยต์ HTTPS เพื่อให้ Elim เรียกเข้ามายังระบบของคุณ ทุกครั้งที่คำสั่งซื้อหรือการชำระเงินเปลี่ยนสถานะ แทนการวนถามสถานะเอง หน้านี้อธิบายอีเวนต์ เอนด์พอยต์จัดการ โครงสร้าง payload การตรวจสอบลายเซ็น และนโยบายลองส่งใหม่

ดูตำแหน่งของ Webhook ในวงจรชีวิตคำสั่งซื้อได้ที่ คู่มือคำสั่งซื้อ และ เอกสารอ้างอิง API คำสั่งซื้อ

ทุกเอนด์พอยต์ต้องยืนยันตัวตนด้วย JWT (Authorization: Bearer <token>) หรือ API Key (x-api-key)

อีเวนต์

จะได้รับเฉพาะอีเวนต์ที่สมัครไว้ โดยทั่วไปสมัครทั้งสองอย่าง

เอนด์พอยต์จัดการการสมัคร

พรีฟิกซ์ /v1/webhooks

เนื้อหาคำขอสร้าง

{
  "url": "https://your-system.example/webhooks/elim",
  "events": ["order.updated", "payment.updated"],
  "is_active": true
}

secret จะคืนค่าเฉพาะทันทีหลังสร้างหรือ rotate-secret เก็บไว้อย่างปลอดภัย เพราะต้องใช้ตรวจสอบทุกคำขอ หากทำ secret หาย ให้เรียก rotate-secret เพื่อออกใหม่ (ลายเซ็นเดิมจะใช้ไม่ได้ทันที)

โครงสร้าง payload

ทั้งสองอีเวนต์ใช้โครงสร้างเดียวกัน ต่างกันแค่ฟิลด์ event:

{
  "id": "evt_4a1f2c...",
  "event": "payment.updated",
  "created_at": "2026-06-19T00:00:00.000Z",
  "data": {
    "order": {
      "id": "ORD0000000123",
      "platform": "taobao",
      "order_id": "123456789",
      "status": "paid",
      "payment_status": "paid",
      "platform_payment_status": "success",
      "total_amount_cny": 123.45,
      "updated_at": "2026-06-19T00:00:00.000Z"
    }
  }
}

การจัดการฝั่งคุณ: ค้นหา data.order.id อัปเดตสถานะคำสั่งซื้อในระบบของคุณ แล้ว ตอบกลับ HTTP 2xx payload อาจมาถึง ไม่เรียงลำดับ — ให้เชื่อ updated_at ที่ใหม่กว่าเสมอ และเพิกเฉยอีเวนต์ที่เก่ากว่าสถานะที่คุณมีอยู่

เฮดเดอร์ในการส่งแต่ละครั้ง

การตรวจสอบลายเซ็น

สตริงสำหรับเซ็น: "{X-Elim-Timestamp}.{เนื้อหา JSON ดิบ}" — ใช้ เนื้อหาดิบตามที่ได้รับ อย่าแปลงแล้ว serialize ใหม่

อัลกอริทึม: HMAC-SHA256(secret, สตริงสำหรับเซ็น) เทียบกับส่วนหลัง sha256= ใน X-Elim-Signature ด้วยการเปรียบเทียบแบบ timing-safe

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyElimWebhook(
  secret: string,
  timestamp: string,
  rawBody: string,
  signature: string,
): boolean {
  const expected = `sha256=${createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')}`;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

ปฏิเสธคำขอที่ X-Elim-Timestamp ต่างจากเวลาปัจจุบันมากเกินไป (เช่น เกิน 5 นาที) เพื่อลดความเสี่ยงการเล่นซ้ำ

นโยบายลองส่งใหม่

ดูผลการส่งแต่ละครั้งที่ GET /v1/webhooks/:id/deliveries ใช้ POST /v1/webhooks/:id/test เพื่อตรวจสอบการตั้งค่ารับข้อมูลอย่างรวดเร็ว

ความปลอดภัย

• URL บนโปรดักชันต้องเป็น HTTPS สภาพแวดล้อม dev ใช้ localhost ได้
• IP ภายใน / private / metadata ถูกบล็อกบนโปรดักชัน
• secret แสดงเฉพาะหลังสร้างหรือ rotate-secret
• payload ไม่มี รหัสผ่าน, API key, JWT หรือ access token ของแพลตฟอร์ม

หากยังไม่ได้ตั้งค่า Webhook

เรียก GET /v1/orders/:id เพื่อสอบถามสถานะโดยตรงได้ตลอดเวลา — ทุกครั้งที่เรียก Elim จะซิงก์สถานะล่าสุดจากแพลตฟอร์มก่อนตอบกลับ ดู เอกสารอ้างอิง API คำสั่งซื้อ

ลิงก์ที่เกี่ยวข้อง

• เอกสารอ้างอิง API คำสั่งซื้อ
• คู่มือคำสั่งซื้อ
• คู่มือการยืนยันตัวตน