อีเวนต์เรียลไทม์
คู่มือ Webhook
อีเวนต์ 10 ประเภท ลายเซ็น HMAC SHA-256 คำนวณจาก body ดิบ และส่งซ้ำได้ 5 ครั้งตามลำดับที่กำหนดไว้ สร้างตัวรับครั้งเดียวใช้ได้กับทุกผลิตภัณฑ์
การส่งทำงานอย่างไร
ภาพรวม
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))แคตาล็อก
แคตาล็อกอีเวนต์
| อีเวนต์ | ยิงเมื่อ | ฟิลด์ใน 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.approved | KYC ของร้านค้าหรือผู้ซื้อผ่านทุกการตรวจ และบัญชีถูกปลดล็อก | 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": "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"
}
}
}ความปลอดภัย
การตรวจลายเซ็น
ตรวจกับไบต์ดิบเท่านั้น
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)
ตรวจโค้ดของคุณกับลายเซ็นจริง
การส่ง
การส่งซ้ำและ timeout
| ครั้งที่ | รอก่อนส่ง | เวลารวม | สถานะ |
|---|---|---|---|
| 1 | 1m | 1m | ลองใหม่ถ้าไม่สำเร็จ |
| 2 | 5m | 6m | ลองใหม่ถ้าไม่สำเร็จ |
| 3 | 30m | 36m | ลองใหม่ถ้าไม่สำเร็จ |
| 4 | 2h | 2h 36m | ลองใหม่ถ้าไม่สำเร็จ |
| 5 | 12h | 14h 36m | ครั้งสุดท้าย |
2xx ใด ๆ ถือว่าสำเร็จ
ตอบ 200 พร้อม body สั้น ๆ การ redirect 3xx ไม่ถือว่าสำเร็จและจะถูกส่งซ้ำ
ตอบเร็ว ค่อยทำงานทีหลัง
ตอบรับก่อนแล้วโยนงานเข้าคิวของคุณเอง ตัวจัดการที่หนักจะทำให้เกิดการส่งซ้ำที่ไม่จำเป็น
ส่งซ้ำได้ทุกรายการ
การส่งที่ตายแล้วยังอยู่ใน event log และสั่งส่งซ้ำได้จากหลังบ้านหรือ API
{ "received": true }Body สั้นเท่านี้ก็เพียงพอสำหรับการตอบรับเช็กลิสต์
เช็กลิสต์ตัวรับ
ตรวจลายเซ็นก่อน parse
ถือว่า body ที่ยังไม่ตรวจลายเซ็นเป็นข้อมูลที่เป็นอันตราย ปฏิเสธด้วย 401 และบันทึกไว้
กันซ้ำด้วย event id
เก็บ id ไว้แล้วข้ามรายการซ้ำ การ retry และ replay ทำให้อีเวนต์เดิมมาถึงได้หลายครั้ง
ตอบกลับภายในเวลาที่กำหนด
ตอบ 200 ทันที อย่ารอ API ของบุคคลที่สามอยู่ในตัวจัดการ
ทำงานแบบอะซิงโครนัส
โยนเข้าคิวของคุณเอง ฐานข้อมูลที่ช้าจะไม่กลายเป็นการส่งที่ล้มเหลว
อย่าสมมติว่าลำดับถูกต้อง
การ retry ทำให้อีเวนต์มาถึงสลับลำดับได้ ใช้ created_at และสถานะของทรัพยากร ไม่ใช่ลำดับที่มาถึง
กระทบยอดเสมอ
ดึงข้อมูลธุรกรรมหรือ settlement มากระทบยอดทุกวัน webhook เป็นทางด่วน ไม่ใช่แหล่งความจริงเดียว