What is a webhook callback?

Webhook callback คืออะไร?

When you create an order with a notify_url, we will POST a JSON payload to that URL once the order reaches a terminal state (paid, success, or failed). This is your asynchronous notification — you do not need to poll.

เมื่อคุณสร้าง order พร้อม notify_url เมื่อ order เข้าสถานะสุดท้าย (paid, success, fail) ระบบจะ POST JSON ไปที่ URL นั้น — ฝั่งคุณไม่ต้อง poll

HTTP request shape

รูปแบบ HTTP request

Every callback we send to your notify_url looks like this at the wire level:

ทุก callback ที่ระบบส่งไปยัง notify_url จะมีรูปแบบดังนี้:

POST /your-callback-path HTTP/1.1
Host: <your-merchant-webhook-URL>
User-Agent: <gateway-user-agent>
Content-Type: application/json
Connection: close
X-Signature: 7b3d4e8f1a2c5b6e9d0f1a2c3b4e5d6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d

{"merchant_id":"AA12345678","platform_order_id":"...","merchant_order_id":"...",...}

Verifying the signature

การตรวจสอบ Signature

Always verify the X-Signature header. Otherwise an attacker can forge fake callbacks and trick your system into marking unpaid orders as paid. The check is the same HMAC-SHA256 over the raw body, using the same secret you use for outgoing requests.

ต้องตรวจสอบ X-Signature ทุกครั้ง — มิฉะนั้น attacker อาจปลอม callback หลอกให้ระบบคุณ mark order ที่ไม่ได้จ่ายเป็น paid — การตรวจสอบใช้ HMAC-SHA256 บน raw body ด้วย secret เดียวกัน กับที่ใช้ส่ง request

# For testing/debugging only — verify a captured callback:
RAW_BODY=$(cat captured-payload.json)
RECEIVED_SIG="<signature from X-Signature header>"
SECRET='YOUR_SECRET'

EXPECTED=$(printf '%s' "$RAW_BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

if [ "$EXPECTED" = "$RECEIVED_SIG" ]; then
  echo "OK"
else
  echo "FAIL: expected=$EXPECTED received=$RECEIVED_SIG"
fi

// Express handler — read the RAW body, then verify
import express from 'express';
import crypto from 'node:crypto';

const SECRET = process.env.GATEWAY_SECRET;
const app = express();

// IMPORTANT: capture raw body BEFORE JSON parsing
app.post('/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const rawBody  = req.body;                                  // Buffer
    const received = req.get('x-signature') || '';
    const expected = crypto.createHmac('sha256', SECRET)
                           .update(rawBody)
                           .digest('hex');

    // Use timing-safe comparison
    const ok = received.length === expected.length &&
               crypto.timingSafeEqual(
                 Buffer.from(received, 'hex'),
                 Buffer.from(expected, 'hex')
               );

    if (!ok) return res.status(401).send('bad signature');

    const event = JSON.parse(rawBody.toString('utf8'));
    // ... handle event idempotently ...
    res.status(200).send('ok');
  }
);

<?php
$secret = getenv('GATEWAY_SECRET');

// Read raw body BEFORE any framework parsing
$rawBody = file_get_contents('php://input');

$received = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $rawBody, $secret);

// Timing-safe comparison
if (!hash_equals($expected, $received)) {
    http_response_code(401);
    echo 'bad signature';
    exit;
}

$event = json_decode($rawBody, true);
// ... handle $event idempotently ...

http_response_code(200);
echo 'ok';

How to acknowledge

วิธีตอบรับ

Respond with HTTP 200 to acknowledge receipt. Any other status code (or a timeout) counts as a failure and we will retry.

ตอบ HTTP 200 เพื่อยืนยันว่ารับได้แล้ว — status อื่นใด (หรือ timeout) ถือเป็นล้มเหลว ระบบจะ retry

Retry policy

นโยบาย Retry

Idempotency — your handler must be safe to call twice

Idempotency — handler ต้อง process ซ้ำได้อย่างปลอดภัย

Duplicate deliveries are possible — for example if your endpoint times out at second 59 but had already updated state, our retry will send the same payload again. Your handler must be able to receive the same callback multiple times without double-counting.

Callback ส่งซ้ำได้ — เช่นถ้า endpoint ของคุณ timeout วินาทีที่ 59 หลัง update state ไปแล้ว ระบบจะ retry ส่ง payload เดิมอีกรอบ — handler ต้องรับ callback ซ้ำได้โดยไม่บวกซ้ำ

Recommended handler pattern

Pattern ที่แนะนำสำหรับ handler

1. Verify signature against the raw body. Reject 401 on mismatch.
2. ตรวจ signature กับ raw body — ถ้าไม่ตรง ตอบ 401
3. Parse JSON. Extract platform_order_id as the unique key.
4. Parse JSON — ใช้ platform_order_id เป็น unique key
5. Insert-or-ignore a row in your callback log table on (platform_order_id, status). If the row already exists with the same status, return 200 immediately — already processed.
6. Insert-or-ignore log table ด้วย (platform_order_id, status) — ถ้ามี row เดียวกันอยู่แล้ว ตอบ 200 ทันที — ประมวลผลไปแล้ว
7. Update your order within a transaction.
8. Update order ภายใน transaction
9. Return 200 only after the DB transaction commits.
10. ตอบ 200 หลัง DB transaction commit สำเร็จเท่านั้น

Security checklist

Checklist ด้านความปลอดภัย

• HTTPS only. Use a TLS-enabled notify_url; we do not enforce TLS at our end but plain HTTP exposes signatures and order data on the wire.
• HTTPS เท่านั้น — ใช้ notify_url ที่เปิด TLS — ระบบเราไม่บังคับ TLS ฝั่งคุณ แต่ HTTP ธรรมดาจะเปิดเผย signature และข้อมูล order
• Always verify X-Signature with timing-safe comparison (crypto.timingSafeEqual, hash_equals).
• ตรวจ X-Signature เสมอ ด้วย timing-safe comparison (crypto.timingSafeEqual, hash_equals)
• Never trust payload values blindly. Cross-check amount and merchant_order_id against your stored order before marking it paid.
• อย่าเชื่อค่าใน payload ทันที — เช็ค amount และ merchant_order_id เทียบกับ order ที่เก็บไว้ก่อน mark ว่าจ่ายแล้ว
• Reject unknown mode values. Currently only PAYMENT and WITHDRAW; unexpected values may indicate a future protocol change you haven't accounted for.
• ปฏิเสธ mode ที่ไม่รู้จัก — ตอนนี้มีแค่ PAYMENT กับ WITHDRAW — ค่าอื่นอาจเป็น protocol ใหม่ในอนาคตที่คุณยังไม่รองรับ
• Don't whitelist source IPs as your only check — our egress IPs may change without notice. Signature verification is the contract.
• อย่าใช้ IP whitelist เป็น check เดียว — IP ออกของระบบเราอาจเปลี่ยน — Signature verification คือหลัก