Xử lý lỗi & Lịch trình Retry
Xử lý lỗi webhook HiTechCloud Pay: cơ chế gửi lại (retry) tự động khi endpoint gặp sự cố, lịch trình thử lại và cách xử lý các mã lỗi thường gặp.
Khi máy chủ webhook của bạn gặp sự cố (quá tải, mất kết nối, timeout hoặc phản hồi mã lỗi 5xx/4xx), HiTechCloud Pay sẽ tự động kích hoạt cơ chế gửi lại (Retry) thông minh theo khoảng thời gian lũy tiến.
Lịch trình Retry tự động
| Lần gửi | Thời gian sau lần gửi trước | Trạng thái |
|---|---|---|
| Lần 1 (Gốc) | Tức thì khi phát sinh giao dịch | Ban đầu |
| Lần 2 | Sau 1 phút | Thử lại lần 1 |
| Lần 3 | Sau 5 phút | Thử lại lần 2 |
| Lần 4 | Sau 15 phút | Thử lại lần 3 |
| Lần 5 | Sau 30 phút | Thử lại lần 4 |
| Lần 6 | Sau 1 giờ | Thử lại lần 5 |
| Lần 7 | Sau 2 giờ | Thử lại lần 6 |
| Lần 8 | Sau 6 giờ | Thử lại lần 7 |
| Lần 9 | Sau 12 giờ | Thử lại lần 8 |
| Lần 10 | Sau 24 giờ | Lần thử cuối cùng trước khi chuyển sang trạng thái Thất bại |
Các nguyên nhân gây lỗi phổ biến & Cách khắc phục
| Mã lỗi / Sự cố | Nguyên nhân | Cách khắc phục |
|---|---|---|
HTTP 404 Not Found | Sai đường dẫn URL webhook hoặc router trên server chưa đăng ký route | Kiểm tra lại URL webhook trên my.hitechcloud.vn |
HTTP 401 Unauthorized | Xác thực HMAC hoặc API Key thất bại | Kiểm tra lại SECRET_KEY hoặc cách đọc raw body |
HTTP 500 Internal Server Error | Lỗi mã nguồn máy chủ (ví dụ: lỗi kết nối CSDL, crash PHP/Node) | Kiểm tra file error log trên server của bạn |
Connection Timeout (> 30s) | Xử lý nghiệp vụ nặng (gửi email, gọi API bên thứ ba) ngay trong luồng webhook | Chuyển các tác vụ nặng vào Message Queue (Redis / RabbitMQ) |
Bắn lại Webhook thủ công (Manual Replay)
Trong trường hợp máy chủ của bạn bị mất điện hoặc bảo trì kéo dài khiến tất cả các lần retry tự động đều thất bại, bạn có thể truy cập https://my.hitechcloud.vn → Webhooks → chọn giao dịch bị lỗi và nhấn nút Gửi lại (Replay) để kích hoạt gửi lại ngay lập tức.
Sau khi hết 10 lần retry mà endpoint vẫn không phản hồi thành công, giao dịch sẽ được đánh dấu 'Thất bại'. Bạn vẫn có thể vào trang Quản lý Webhooks trên
my.hitechcloud.vn để bấm nút 'Gửi lại thủ công' bất kỳ lúc nào.