Gửi lại và nhật ký giao

Hệ thống của bạn có thể tạm thời không nhận được webhook (bảo trì, lỗi mạng, quá tải). hoadon.pro vì vậy tự thử lại các lượt giao thất bại, và ghi nhật ký từng lượt để bạn kiểm tra.

Khi nào một lượt giao được coi là thành công

Hệ thống của bạn trả mã trạng thái 2xx. Mọi kết quả khác, gồm mã 4xx, 5xx và lỗi kết nối, được coi là thất bại và sẽ được thử lại.

Thử lại

hoadon.pro thử lại với khoảng chờ tăng dần theo cấp số nhân, trong tối đa 24 giờ kể từ lúc sự kiện phát sinh. Sau thời hạn đó, lượt giao được đánh dấu thất bại hẳn nhưng vẫn xem được trong nhật ký giao.

Vì sự kiện có thể được gửi lại, hãy thiết kế bên nhận idempotent:

• Lưu id của mọi sự kiện đã xử lý và bỏ qua id đã thấy.
• Đừng giả định sự kiện đến đúng thứ tự phát sinh. Với invoice.updated, nên đọc lại trạng thái mới nhất của hoá đơn qua API nếu thứ tự quan trọng.
• Trả 2xx ngay khi đã lưu sự kiện; xử lý nghiệp vụ nặng ở hàng đợi riêng để không bị coi là thất bại do chậm.

Nhật ký giao

Mỗi lượt giao được ghi lại: thời điểm, mã phản hồi, độ trễ và số lần thử. Xem nhật ký ở thẻ API và Webhook trong ứng dụng (Webhook).

Gỡ lỗi khi không nhận được sự kiện

Dấu hiệu	Nguyên nhân thường gặp
Không có lượt giao nào trong nhật ký	Webhook chưa đăng ký sự kiện đó, hoặc sự kiện thuộc tổ chức webhook không được truy cập.
Có lượt giao, phản hồi 4xx	URL sai, hoặc hệ thống của bạn từ chối do xác thực chữ ký thất bại (Chữ ký).
Có lượt giao, phản hồi 5xx hoặc quá thời gian	Hệ thống của bạn lỗi hoặc xử lý quá chậm. Trả 2xx sớm hơn.
Sự kiện tới nhiều lần	Bình thường khi thử lại; loại trùng theo id.

Bảo mật điểm nhận

• Chỉ chấp nhận yêu cầu có chữ ký hợp lệ.
• Dùng HTTPS.
• Nếu nghi ngờ lộ secret, tạo lại điểm nhận với secret mới và xoá điểm nhận cũ.