ข้ามไปยังเนื้อหาหลัก

อีเวนต์เรียลไทม์

คู่มือ Webhook

อีเวนต์ 10 ประเภท ลายเซ็น HMAC SHA-256 คำนวณจาก body ดิบ และส่งซ้ำได้ 5 ครั้งตามลำดับที่กำหนดไว้ สร้างตัวรับครั้งเดียวใช้ได้กับทุกผลิตภัณฑ์

การส่งทำงานอย่างไร

ภาพรวม

PAYDY จะ POST JSON ไป endpoint HTTPS ของคุณทันทีที่มีอะไรเปลี่ยน มี header สามตัวบอกว่าอีเวนต์อะไรมา เป็นการส่งครั้งไหน และพิสูจน์ได้อย่างไรว่ามาจากเรา

10

ประเภทอีเวนต์

เลือกรับชุดไหนก็ได้

SHA-256

ลายเซ็น

HMAC จาก body ดิบ

10s

เวลารอตอบกลับ

ตอบ 2xx ภายในเวลานี้

5

จำนวนครั้งที่ส่ง

1m → 5m → 30m → 2h → 12h

หน้าตาของการส่งหนึ่งครั้ง
POST /webhooks/paydy HTTP/1.1
Content-Type: application/json
PAYDY.ai-Event: payment.success
PAYDY.ai-Delivery: 01JQ8XJ1DELIVERY00000001
PAYDY.ai-Signature: 9f2c…(hex, HMAC SHA-256 (hex))
X-Paydy-Timestamp: 1794096000
X-Paydy-Signature-V2: 4b1e…(hex, HMAC SHA-256 (hex))

แคตาล็อก

แคตาล็อกอีเวนต์

อีเวนต์ทั้ง 10 ประเภท พร้อมฟิลด์ที่เชื่อถือได้ใน data สมัครรับเฉพาะที่คุณจัดการจริง อีเวนต์ที่ไม่สมัครจะไม่ถูกคิวไว้
แคตาล็อกอีเวนต์
อีเวนต์ยิงเมื่อฟิลด์ใน data
payment.successเกตเวย์ยืนยันการชำระเงินแล้ว และรายละเอียดค่าธรรมเนียมสรุปแล้ว
transaction_idamountcurrencymethodfeecustomermetadata
payment.failedรายการถูกปฏิเสธ หมดเวลา หรือถูกทิ้ง failure_code จะบอกว่าควร retry หรือไม่
transaction_idfailure_codefailure_messagemethodretryable
refund.completedการคืนเงินทั้งจำนวนหรือบางส่วนถึงผู้จ่ายแล้ว
refund_idtransaction_idamountremaining_refundablecompleted_at
settlement.completedรอบ settlement ถูกโอนเข้าบัญชีธนาคารของคุณแล้ว
settlement_idperiodnet_amountbanktransactions
kyc.approvedKYC ของร้านค้าหรือผู้ซื้อผ่านทุกการตรวจ และบัญชีถูกปลดล็อก
merchant_idlevelchecksapproved_at
kyc.rejectedการตรวจ KYC ไม่ผ่าน reason_code และ failed_checks บอกว่าข้อไหนและยื่นใหม่ได้หรือไม่
merchant_idreason_codefailed_checkscan_resubmit
subscription.chargedการตัดเงินตามรอบสำเร็จ และเริ่มรอบบิลใหม่แล้ว
subscription_idtransaction_idamountperiod_startperiod_end
subscription.failedการตัดเงินตามรอบล้มเหลว next_retry_at บอกครั้งถัดไปตามลำดับวันที่ 1/3/7
subscription_idattemptnext_retry_atfailure_code
easylater.approvedคำขอ PAYDY Later ได้รับอนุมัติ พร้อมวงเงินและรหัสสัญญาที่ลงนามแล้ว
application_idcustomer_idcredit_typelimitbureau_score
order.status_changedออเดอร์เปลี่ยนสถานะ รวมถึงเลขติดตามเมื่อจัดส่งแล้ว
order_idfromtotracking_numbercarrier

โครงสร้าง

โครงสร้าง Payload

ทุกการส่งใช้โครงสร้างเดียวกัน: id, event, created_at และ data ให้ใช้ id เป็นกุญแจในตัวจัดการ เพราะอีเวนต์หนึ่งอาจมาถึงมากกว่าหนึ่งครั้ง
payment.success
{
  "id": "01JQ8XJ1DELIVERY00000001",
  "event": "payment.success",
  "created_at": "2026-10-14T09:14:02.000Z",
  "data": {
    "transaction_id": "01JQ8W4M3K1L2N5P6Q7R8S9T0U",
    "payment_link_id": "01JQ8VXKP3R2M4N5Q6S7T8U9V0",
    "amount": 129000,
    "currency": "THB",
    "method": "promptpay",
    "fee": {
      "mdr_amount": 1935,
      "vat": 135,
      "net_amount": 126930
    },
    "customer": {
      "email": "somchai@example.com",
      "name": "สมชาย ใจดี"
    },
    "metadata": {
      "order_id": "ORD-2026-10428"
    }
  }
}

ความปลอดภัย

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

PAYDY.ai-Signature บรรจุค่า HMAC SHA-256 (hex) ที่คำนวณจาก body ของคำขอตรง ๆ โดยใช้ secret ของ endpoint คุณ ให้เทียบแบบ constant time ก่อนจะเชื่อฟิลด์ใดก็ตาม

ตรวจกับไบต์ดิบเท่านั้น

ถ้า parse JSON แล้ว serialise ใหม่ ไบต์จะเปลี่ยนและค่า digest จะไม่ตรงเลย ให้เก็บ body ดิบก่อน ตรวจลายเซ็น แล้วจึง parse และต้องเทียบด้วยฟังก์ชันที่ปลอดภัยต่อเวลา ไม่ใช่ ==
Node.js / Express
import crypto from 'node:crypto';
import express from 'express';

const app = express();

// IMPORTANT: verify against the RAW body bytes, never the parsed JSON.
app.post(
  '/webhooks/paydy',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const received = req.header('PAYDY.ai-Signature') ?? '';
    const expected = crypto
      .createHmac('sha256', process.env.PAYDY_WEBHOOK_SECRET)
      .update(req.body)
      .digest('hex');

    const ok =
      received.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

    if (!ok) return res.status(401).json({ error: 'bad_signature' });

    const evt = JSON.parse(req.body.toString('utf8'));
    // Deliveries can repeat — key your handler on evt.id.
    switch (evt.event) {
      case 'payment.success':
        void fulfilOrder(evt.data.metadata.order_id);
        break;
      case 'refund.completed':
        void reverseOrder(evt.data.transaction_id);
        break;
    }

    res.status(200).json({ received: true });
  },
);

ทางเลือก: ลายเซ็นแบบมีเวลากำกับ (v2)

ทุกการส่งมี X-Paydy-Timestamp (วินาทีแบบ Unix) และ X-Paydy-Signature-V2 ซึ่งเป็น HMAC SHA-256 แบบ hex ของ <X-Paydy-Timestamp>.<raw body> ด้วย secret เดิม การตรวจลายเซ็นนี้ช่วยปฏิเสธการส่งซ้ำได้ เช่น ไม่รับรายการที่เก่ากว่า 300 วินาที ส่วน PAYDY.ai-Signature ยังเหมือนเดิม ระบบที่เชื่อมต่ออยู่แล้วจึงทำงานต่อได้ทันที

ตรวจโค้ดของคุณกับลายเซ็นจริง

สนามทดลองใน sandbox คำนวณ HMAC SHA-256 จริงของ payload ตัวอย่างในเบราว์เซอร์คุณ ด้วย secret เดโมที่เปิดเผยไว้ คุณจึงยืนยันตัวตรวจของคุณกับค่าที่ถูกต้องแน่นอนได้ เปิดสนามทดลอง →

การส่ง

การส่งซ้ำและ timeout

ถ้า endpoint ของคุณไม่ตอบ 2xx ภายใน 10 วินาที ระบบจะส่งซ้ำตามลำดับที่กำหนดไว้ สูงสุด 5 ครั้ง หลังจากนั้นจะถูกทำเครื่องหมายว่าตายและรอการส่งซ้ำด้วยมือ
การส่งซ้ำและ timeout
ครั้งที่รอก่อนส่งเวลารวมสถานะ
11m1mลองใหม่ถ้าไม่สำเร็จ
25m6mลองใหม่ถ้าไม่สำเร็จ
330m36mลองใหม่ถ้าไม่สำเร็จ
42h2h 36mลองใหม่ถ้าไม่สำเร็จ
512h14h 36mครั้งสุดท้าย

2xx ใด ๆ ถือว่าสำเร็จ

ตอบ 200 พร้อม body สั้น ๆ การ redirect 3xx ไม่ถือว่าสำเร็จและจะถูกส่งซ้ำ

ตอบเร็ว ค่อยทำงานทีหลัง

ตอบรับก่อนแล้วโยนงานเข้าคิวของคุณเอง ตัวจัดการที่หนักจะทำให้เกิดการส่งซ้ำที่ไม่จำเป็น

ส่งซ้ำได้ทุกรายการ

การส่งที่ตายแล้วยังอยู่ใน event log และสั่งส่งซ้ำได้จากหลังบ้านหรือ API

200{ "received": true }Body สั้นเท่านี้ก็เพียงพอสำหรับการตอบรับ

เช็กลิสต์

เช็กลิสต์ตัวรับ

หกนิสัยที่แยกตัวรับ webhook ซึ่งรอดใน production ออกจากตัวที่ทำเงินหายเงียบ ๆ
  • ตรวจลายเซ็นก่อน parse

    ถือว่า body ที่ยังไม่ตรวจลายเซ็นเป็นข้อมูลที่เป็นอันตราย ปฏิเสธด้วย 401 และบันทึกไว้

  • กันซ้ำด้วย event id

    เก็บ id ไว้แล้วข้ามรายการซ้ำ การ retry และ replay ทำให้อีเวนต์เดิมมาถึงได้หลายครั้ง

  • ตอบกลับภายในเวลาที่กำหนด

    ตอบ 200 ทันที อย่ารอ API ของบุคคลที่สามอยู่ในตัวจัดการ

  • ทำงานแบบอะซิงโครนัส

    โยนเข้าคิวของคุณเอง ฐานข้อมูลที่ช้าจะไม่กลายเป็นการส่งที่ล้มเหลว

  • อย่าสมมติว่าลำดับถูกต้อง

    การ retry ทำให้อีเวนต์มาถึงสลับลำดับได้ ใช้ created_at และสถานะของทรัพยากร ไม่ใช่ลำดับที่มาถึง

  • กระทบยอดเสมอ

    ดึงข้อมูลธุรกรรมหรือ settlement มากระทบยอดทุกวัน webhook เป็นทางด่วน ไม่ใช่แหล่งความจริงเดียว

Webhook Reference — เอกสารนักพัฒนา PAYDY.ai · PAYDY.ai