Webhook Callback
เมื่อ Job การตรวจสอบแบบ async เสร็จ EasySlip จะส่งผลไปที่ callbackUrl ของคุณด้วย HTTP POST หน้านี้อธิบาย payload ของ callback, ลายเซ็นที่ต้องตรวจ และการ retry
แบบ async รองรับสลิปธนาคารเท่านั้น กรณี success ฟิลด์ data จะตรงกับ Response ของ POST /verify/bank แบบ sync กรณี failed จะได้ data: null และมี error บอกสาเหตุ
การส่ง (Delivery)
- 1 ผลลัพธ์ต่อ 1 สลิป ทุกสลิป รวมถึงสลิปใน batch มี callback ของตัวเอง และการ retry อาจทำให้ได้ callback เดิมซ้ำ
- Method:
POSTพร้อมContent-Type: application/jsonและUser-Agent: EasySlip-Webhook/2.0 - ไม่ตาม redirect และใช้ timeout เริ่มต้น 5 วินาทีต่อการส่ง ควรตอบกลับให้เร็ว
- ปลายทาง:
callbackUrlจากคำขอ หรือ Default Webhook URL ของ branch หากไม่ได้ระบุมา - ปลายทางของคุณตอบสถานะ 2xx ตัวไหนก็ได้ ถ้าตอบที่ไม่ใช่ 2xx (หรือ timeout) ระบบจะ retry
Request Body
{
"jobId": "3f2b1c8a-9d4e-4f10-b7a2-6c5d4e3f2a1b",
"batchId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"status": "success",
"data": {
"remark": "Order #1001",
"isDuplicate": false,
"amountInSlip": 1500.00,
"isAmountMatched": true,
"rawSlip": {
"payload": "00000000000000000000000000000000000000",
"transRef": "68370160657749I376388B35",
"date": "2024-01-15T14:30:00+07:00",
"countryCode": "TH",
"amount": {
"amount": 1500.00,
"local": { "amount": 1500.00, "currency": "THB" }
},
"fee": 0,
"ref1": "",
"ref2": "",
"ref3": "",
"sender": {
"bank": { "id": "004", "name": "กสิกรไทย", "short": "KBANK" },
"account": {
"name": { "th": "นาย ผู้โอน ทดสอบ", "en": "MR. SENDER TEST" },
"bank": { "type": "BANKAC", "account": "123-4-xxxxx-5" }
}
},
"receiver": {
"bank": { "id": "014", "name": "ไทยพาณิชย์", "short": "SCB" },
"account": {
"name": { "th": "บริษัท ตัวอย่าง จำกัด" },
"bank": { "type": "BANKAC", "account": "xxx-x-x5678-x" }
},
"merchantId": null
}
}
},
"timestamp": "2024-01-15T14:32:05+07:00"
}ฟิลด์
| ฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|
jobId | string | UUID ของ Job (ตรงกับ jobId ที่คุณได้ตอนส่งเข้าคิว) |
batchId | string | null | UUID ของ batch ถ้าสลิปอยู่ใน batch ถ้าไม่ใช่จะเป็น null |
status | string | success, not_found หรือ failed (ดูด้านล่าง) |
data | object | null | ผลตรวจแบบ sync เมื่อสำเร็จ; บริบทเมื่อ not_found; null เมื่อ failed |
error | object | มีเฉพาะ failed: code และ message ที่ไม่เปิดเผยข้อมูลภายใน |
timestamp | string | เวลา ISO 8601 ที่สร้างผลลัพธ์ |
ค่าของ status
status | ความหมาย | data |
|---|---|---|
success | ตรวจสอบสลิปสำเร็จ | ผลการตรวจสอบเต็มรูปแบบ |
not_found | ยังไม่พบสลิปหลัง retry ครบแล้ว | บริบทการตรวจ ไม่มีสลิปที่ยืนยันแล้ว |
failed | ตรวจต่อไม่ได้เนื่องจาก error หรือข้อจำกัดบัญชี/บริการ | null; ดู error |
Type definition
type WebhookPayload = {
jobId: string;
batchId: string | null;
timestamp: string; // ISO 8601
} & (
| { status: 'success'; data: VerifyBankData }
| { status: 'not_found'; data: unknown }
| { status: 'failed'; data: null; error: { code: string; message: string } }
);ตรวจสอบล้มเหลว
{
"jobId": "3f2b1c8a-9d4e-4f10-b7a2-6c5d4e3f2a1b",
"batchId": null,
"status": "failed",
"data": null,
"error": {
"code": "API_SERVER_ERROR",
"message": "External API service is temporarily unavailable"
},
"timestamp": "2026-09-11T00:00:00.000Z"
}ตัวอย่าง code เช่น QUOTA_EXCEEDED, SERVICE_EXPIRED, BRANCH_INACTIVE, VALIDATION_ERROR, API_SERVER_ERROR และ RENEWAL_TEMPORARILY_UNAVAILABLE ส่วน error ที่ระบบไม่รู้จักจะใช้ INTERNAL_SERVER_ERROR โดยไม่เปิดเผย exception ภายใน กรณี billing ระบบจะส่ง failed หลัง retry ของ billing ครบแล้วเท่านั้น ระหว่าง retry จะไม่ส่ง
เมื่อส่ง failure callback สำเร็จ Job ยังเป็น failed ไม่เปลี่ยนเป็น done ถ้าส่ง callback ไม่สำเร็จจนหมดรอบ ผล polling ยังคง error.code/message ที่เป็นต้นเหตุไว้ และเพิ่ม error.webhook: "failed" พร้อมรายละเอียดการส่ง ส่วน HTTP error ที่ปฏิเสธคำขอ ก่อนรับเข้าคิว จะไม่มี callback
การตรวจสอบลายเซ็น (Signature Verification)
Header ลายเซ็นจะมีเฉพาะเมื่อ Branch ตั้ง Webhook Secret ไว้แล้ว ถ้ายังไม่ได้ตั้ง callback จะไม่มีลายเซ็น ควรตั้ง Secret ก่อนขึ้น production แล้วปฏิเสธคำขอที่ไม่มีลายเซ็นหรือตรวจไม่ผ่าน
EASYSLIP_WEBHOOK_SECRET ในตัวอย่างด้านล่างคือ environment variable ฝั่งระบบรับ callback ของคุณ ที่เก็บ Secret ของ Branch ไว้ ไม่ใช่ env ส่วนกลางตัวใหม่ของ EasySlip API หรือ worker
X-EasySlip-Signature: sha256=<hmac>ลายเซ็นคือ HMAC-SHA256 ของ raw JSON request body โดยใช้ Webhook Secret ของ Branch เป็นกุญแจ เข้ารหัสเป็น hex
วิธีตรวจ: คำนวณ HMAC-SHA256 ของ raw body ที่ได้รับ (byte ตามจริง ก่อน parse หรือ serialize JSON ใหม่) ด้วย secret ของคุณ แล้วเทียบกับค่า hex ใน Header แบบ constant-time
ใช้ raw body
คำนวณ HMAC จาก byte ของ raw request body ไม่ใช่จากออบเจกต์ที่ serialize ใหม่ เพราะการเข้ารหัส JSON ใหม่อาจเปลี่ยน whitespace หรือลำดับ key จนลายเซ็นไม่ตรง ให้เก็บ raw body ไว้ก่อน parse
import express from 'express';
import crypto from 'crypto';
const WEBHOOK_SECRET = process.env.EASYSLIP_WEBHOOK_SECRET;
const app = express();
// จับ RAW body ไว้เพื่อตรวจสอบลายเซ็น
app.post('/webhooks/easyslip',
express.raw({ type: 'application/json' }),
(req, res) => {
const header = req.get('X-EasySlip-Signature') || '';
const expected = 'sha256=' + crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(req.body) // req.body เป็น Buffer (raw bytes)
.digest('hex');
const ok =
/^sha256=[0-9a-f]{64}$/.test(header) &&
crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
if (!ok) return res.status(400).send('invalid signature');
const event = JSON.parse(req.body.toString('utf8'));
// ... จัดการ event.jobId / event.status / event.data ...
res.sendStatus(200);
});<?php
$secret = getenv('EASYSLIP_WEBHOOK_SECRET');
$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_EASYSLIP_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $header)) {
http_response_code(400);
exit('invalid signature');
}
$event = json_decode($raw, true);
// ... จัดการ $event['jobId'] / $event['status'] / $event['data'] ...
http_response_code(200);import hmac, hashlib, os
from flask import Flask, request, abort
WEBHOOK_SECRET = os.environ["EASYSLIP_WEBHOOK_SECRET"].encode()
app = Flask(__name__)
@app.post("/webhooks/easyslip")
def easyslip_webhook():
raw = request.get_data() # raw bytes
header = request.headers.get("X-EasySlip-Signature", "")
expected = "sha256=" + hmac.new(WEBHOOK_SECRET, raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, header):
abort(400)
event = request.get_json()
# ... จัดการ event["jobId"] / event["status"] / event["data"] ...
return "", 200Retries
การ retry ฝั่งตรวจสลิปกับฝั่งส่ง callback นับแยกกัน:
ตรวจสลิป: กรณี
not_foundทุกธนาคารและ BBL pending นับรอบรวมกัน คือครั้งแรก + retry 4 ครั้ง เว้น 30 / 60 / 120 / 240 วินาที พบเมื่อไรก็จบทันที ถ้าครบแล้วยังไม่พบจะส่งnot_foundไม่ใช่failedเวลารอตามตารางรวม 7 นาที 30 วินาที ยังไม่นับเวลาประมวลผล รอคิว และการเลื่อนอื่น ๆ ตัวเลขนี้จึงไม่ใช่เวลาสูงสุดที่งานจะจบส่ง callback: ทุกผล (
success,not_foundและfailed) ส่งครั้งแรก + retry 3 ครั้ง เว้น 10 / 30 / 120 วินาที retry เมื่อได้สถานะที่ไม่ใช่ 2xx ทุกแบบ รวม 4xx และ timeout/network errorถึงส่ง Webhook ไม่สำเร็จเลยสักครั้ง ก็ยังดึงผลได้ทาง
GET /verify/bank/jobs/:jobIdภายใน ~7 วันทำ handler ให้ idempotent เพราะ retry อาจส่ง
jobIdเดิมมาหลายครั้ง ให้กันซ้ำด้วยjobIdตอบ
2xxให้เร็ว แล้วค่อยทำงานหนักแบบ asynchronous จะได้ไม่ timeout จนเกิด retry ที่ไม่จำเป็น
แนวทางที่แนะนำ
- ตรวจสอบลายเซ็น ทุกคำขอก่อนเชื่อถือ body
- ตอบ 2xx เร็ว ๆ แล้วค่อยประมวลผลนอกรอบ
- กันซ้ำด้วย
jobIdเพราะอาจได้ callback ซ้ำ และถ้า retry ครบแล้วยังส่งไม่สำเร็จ ระบบไม่รับประกันว่าจะส่งถึง - กระทบยอดด้วย polling ถ้าไม่ได้ Webhook ภายในเวลาที่คาดไว้ ให้เรียก
GET .../jobs/:jobId - เก็บ secret เป็นความลับ อย่าให้ Webhook Secret หลุดไปอยู่ฝั่ง client