Webhook (IPN)

Webhook (IPN — Instant Payment Notification) là cơ chế Tingee chủ động đẩy thông báo đến máy chủ của đối tác ngay khi có biến động giao dịch, thay vì đối tác phải liên tục polling API.

---

Luồng hoạt động

🔗Luồng xử lý Webhook (IPN)

✅

Giao dịch
thành công

→

📤

Tingee POST
về Webhook URL

→

🔐

Verify
signature

→

🛒

Cập nhật
đơn hàng

→

🟢

Trả về
HTTP 200

---

Xác thực chữ ký

Mỗi request webhook từ Tingee mang header x-signature. Đối tác phải xác minh trước khi xử lý:

Node.js

const crypto = require('crypto');

function verifyWebhookSignature(secretToken, requestTimestamp, body, receivedSignature) {
  const expected = crypto
    .createHmac('sha512', secretToken)
    .update(`${requestTimestamp}:${JSON.stringify(body)}`)
    .digest('hex');
  return expected === receivedSignature;
}

Python

import hmac, hashlib, json

def verify_signature(secret_token: str, timestamp: str, body: dict, received: str) -> bool:
    message = f"{timestamp}:{json.dumps(body, separators=(',', ':'))}"
    expected = hmac.new(secret_token.encode(), message.encode(), hashlib.sha512).hexdigest()
    return hmac.compare_digest(expected, received)

Bỏ qua nếu sai chữ ký

Nếu x-signature không khớp, bỏ qua hoàn toàn request đó. Đây có thể là tấn công giả mạo.

---

Chính sách Retry

Nếu endpoint trả về lỗi (không phải HTTP 200) hoặc timeout, Tingee tự động gửi lại:

Lần retry	Sau bao lâu
Retry 1	30 giây
Retry 2	2 phút
Retry 3	10 phút
Retry 4	1 giờ
Retry 5	6 giờ

Idempotency

Luôn dùng transactionId hoặc orderId để kiểm tra xem đơn hàng đã xử lý chưa, tránh trùng lặp khi nhận retry.

---

Danh mục sự kiện

Loại sự kiện	Mô tả
PAYMENT_SUCCESS	Giao dịch QR / VA thành công
DEEPLINK_RETURN	Kết quả thanh toán qua Deep Link
DIRECT_DEBIT_RESULT	Kết quả trích nợ Direct Debit

Xem chi tiết cấu trúc payload tại Webhook Payment Callback.