Skip to content

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 ​

json
{
  "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"
}

ฟิลด์ ​

ฟิลด์ประเภทคำอธิบาย
jobIdstringUUID ของ Job (ตรงกับ jobId ที่คุณได้ตอนส่งเข้าคิว)
batchIdstring | nullUUID ของ batch ถ้าสลิปอยู่ใน batch ถ้าไม่ใช่จะเป็น null
statusstringsuccess, not_found หรือ failed (ดูด้านล่าง)
dataobject | nullผลตรวจแบบ sync เมื่อสำเร็จ; บริบทเมื่อ not_found; null เมื่อ failed
errorobjectมีเฉพาะ failed: code และ message ที่ไม่เปิดเผยข้อมูลภายใน
timestampstringเวลา ISO 8601 ที่สร้างผลลัพธ์

ค่าของ status ​

statusความหมายdata
successตรวจสอบสลิปสำเร็จผลการตรวจสอบเต็มรูปแบบ
not_foundยังไม่พบสลิปหลัง retry ครบแล้วบริบทการตรวจ ไม่มีสลิปที่ยืนยันแล้ว
failedตรวจต่อไม่ได้เนื่องจาก error หรือข้อจำกัดบัญชี/บริการnull; ดู error

Type definition

typescript
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 } }
);

ตรวจสอบล้มเหลว ​

json
{
  "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

http
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

javascript
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
<?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);
python
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 "", 200

Retries ​

การ 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 ที่ไม่จำเป็น

แนวทางที่แนะนำ ​

  1. ตรวจสอบลายเซ็น ทุกคำขอก่อนเชื่อถือ body
  2. ตอบ 2xx เร็ว ๆ แล้วค่อยประมวลผลนอกรอบ
  3. กันซ้ำด้วย jobId เพราะอาจได้ callback ซ้ำ และถ้า retry ครบแล้วยังส่งไม่สำเร็จ ระบบไม่รับประกันว่าจะส่งถึง
  4. กระทบยอดด้วย polling ถ้าไม่ได้ Webhook ภายในเวลาที่คาดไว้ ให้เรียก GET .../jobs/:jobId
  5. เก็บ secret เป็นความลับ อย่าให้ Webhook Secret หลุดไปอยู่ฝั่ง client

Bank Slip Verification API for Thai Banking