Webhooks · Phản hồi, Retry & Logs

#Quy tắc phản hồi

Máy chủ của bạn báo cho QHTech biết đã nhận webhook thành công bằng mã trạng thái HTTP:

Phản hồi của bạn	QHTech hiểu là
HTTP 2xx (200–299)	Thành công — không gửi lại
Bất kỳ mã khác (4xx, 5xx) hoặc không phản hồi / timeout	Thất bại — sẽ thử lại

QHTech chỉ xét mã HTTP, không xét nội dung body. Chỉ cần trả về 200 OK là đủ; bạn không bắt buộc phải trả JSON nào cụ thể. Dù vậy, trả về {"success": true} là thói quen tốt.

Nên xử lý bất đồng bộ: hãy trả 200 càng sớm càng tốt rồi đẩy phần xử lý nghiệp vụ nặng vào hàng đợi (queue/job). Nếu bạn xử lý đồng bộ mà chậm, request có thể timeout và bị tính là thất bại.

#Cơ chế thử lại (Retry)

Nếu lần gửi đầu tiên không nhận được HTTP 2xx:

1. QHTech lên lịch gửi lại sau 5 phút.
2. Tác vụ gửi lại sẽ cố tối đa 3 lần.

Vì vậy một giao dịch có thể tạo ra nhiều lần gọi tới webhook của bạn nếu các lần trước thất bại.

#Đảm bảo idempotency (chống xử lý trùng)

Do có retry (và bạn có thể gửi lại thủ công từ dashboard), webhook của bạn cần an toàn khi nhận trùng: cùng một giao dịch có thể đến nhiều lần.

• Dùng transaction_id (hoặc referenceCode) làm khoá duy nhất.
• Trước khi xử lý, kiểm tra giao dịch đã xử lý chưa; nếu rồi thì bỏ qua nhưng vẫn trả HTTP 200.

// Ví dụ: chống trùng bằng transaction_id
if (ProcessedTransaction::where('transaction_id', $data['transaction_id'])->exists()) {
    return response()->json(['success' => true]); // đã xử lý -> vẫn trả 200
}

ProcessedTransaction::create(['transaction_id' => $data['transaction_id']]);
// ... xử lý nghiệp vụ ...

#Nhật ký Webhook (Logs)

Mọi lần gửi webhook đều được ghi lại trong dashboard tại Webhooks → Nhật ký (/webhookslog). Mỗi bản ghi lưu:

Thông tin	Mô tả
Payload gửi đi	Toàn bộ JSON QHTech đã gửi
Phản hồi	Nội dung phản hồi máy chủ bạn trả về
Mã HTTP	Mã trạng thái nhận được
URL & phương thức	URL đích và POST
Giao dịch liên quan	Giao dịch tương ứng

Tại đây bạn có thể gửi lại thủ công một webhook cho giao dịch bất kỳ — hữu ích khi endpoint của bạn từng gặp sự cố và cần đồng bộ lại.

#Danh sách kiểm tra khi tích hợp

• Endpoint webhook chạy trên HTTPS.
• Xác thực token ở mọi request (xem Payload & Xác thực).
• Trả HTTP 200 ngay khi đã nhận; xử lý nặng đưa vào queue.
• Chống trùng bằng transaction_id / referenceCode.
• Kiểm tra transferType để chỉ xử lý đúng chiều tiền cần thiết.
• Đối chiếu định kỳ với API Lịch sử giao dịch như phương án dự phòng.