Best Practices

Bảo mật

1. Luôn xác thực chữ ký webhook

Không bao giờ xử lý webhook mà không xác thực HMAC-SHA256. Xem Xác thực chữ ký Webhook.

2. Sử dụng HTTPS

Webhook endpoint phải dùng HTTPS để mã hóa dữ liệu trong quá trình truyền.

3. Lưu secret an toàn

# Đúng: Dùng biến môi trường
THUEAPI_WEBHOOK_SECRET=your_secret_here

# Sai: Hardcode trong code
$secret = "your_secret_here"; // KHÔNG LÀM NÀY

4. Whitelist IP (nâng cao)

Liên hệ [email protected] để lấy danh sách IP của ThueAPI server và chỉ cho phép các IP đó gọi webhook.

Hiệu năng

1. Phản hồi nhanh, xử lý sau

<?php
// Đúng: Dispatch queue job, phản hồi ngay
ProcessBankTransaction::dispatch($transaction);
return response()->json(['success' => true]); // Phản hồi ngay

// Sai: Xử lý đồng bộ rồi mới phản hồi (có thể timeout)
sendEmail($transaction);  // Tốn 5 giây
updateDatabase($transaction);  // Tốn 2 giây
return response()->json(['success' => true]); // Quá muộn

2. Cache kết quả API

<?php
// Cache danh sách tài khoản trong 5 phút
$accounts = Cache::remember('bank_accounts', 300, function() {
    return ThueApiClient::getBankAccounts();
});

Độ tin cậy

1. Xử lý idempotent

Luôn kiểm tra transactionNumber để tránh xử lý cùng một giao dịch hai lần (do webhook retry).

2. Logging đầy đủ

<?php
// Log mọi webhook nhận được
Log::info('ThueAPI webhook received', [
    'ip'           => $request->ip(),
    'transactions' => count($request->input('transactions', [])),
]);

// Log lỗi xác thực
Log::warning('ThueAPI webhook: invalid signature', ['ip' => $request->ip()]);

3. Monitoring

• Theo dõi số lượng webhook nhận được mỗi phút
• Alert khi không nhận webhook trong 30 phút (có thể endpoint của bạn bị lỗi)
• Kiểm tra Dashboard → Webhooks → Lịch sử để xem các lần gửi thất bại

Testing

# Giả lập webhook bằng cURL để test endpoint
curl -X POST https://your-domain.com/webhook/thueapi \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $(echo -n '{"transactions":[{"id":"test"}]}' | openssl dgst -sha256 -hmac 'YOUR_SECRET' | cut -d' ' -f2)" \
  -d '{"transactions":[{"id":"test","gateway":"ACB","transactionDate":"2025-10-14 10:59:30","transactionNumber":"TEST001","accountNumber":"19354957","content":"Test payment","transferType":"IN","transferAmount":100000}]}'