Retry policy
Khi Zorio đẩy webhook đến receiver mà bị fail (timeout / non-2xx / network error), hệ thống sẽ retry tự động theo lịch tăng dần.
Định nghĩa fail
Receiver được coi là fail nếu:
- Timeout sau 5 giây không trả response.
- Trả về HTTP status không phải 2xx (vd 500, 502, 503, 4xx).
- Connection error (DNS fail, TLS handshake fail, ...).
Receiver xử lý lâu?
Bạn nên trả HTTP 200 ngay khi nhận (sau khi verify HMAC), rồi xử lý event async qua queue nội bộ. Không xử lý đồng bộ với Zorio — sẽ bị retry chồng.
Lịch retry
| Lần | Sau bao lâu kể từ lần trước | Cumulative |
|---|---|---|
| 1 (lần đầu) | — | 0s |
| 2 | 30 giây | 30s |
| 3 | 5 phút | 5m 30s |
| 4 (lần cuối) | 30 phút | 35m 30s |
Sau lần 4 fail → event chuyển trạng thái deadletter trong audit log.
Deadletter
Khi event vào deadletter:
- Lưu trong bảng nhật ký phân phối webhook 30 ngày.
- Admin có thể vào Admin Console → Webhook deliveries xem chi tiết: payload, lý do fail, response của receiver.
- KHÔNG retry tự động sau khi đã deadletter — cần fix bug ở receiver rồi:
- Hoặc bấm Replay trên từng delivery để gửi lại.
- Hoặc đăng ký lại webhook để event mới tiếp tục.
Đảm bảo idempotency ở receiver
Vì Zorio có thể retry, receiver PHẢI idempotent — xử lý cùng 1 event nhiều lần không gây hậu quả lệch (vd không tạo 2 bản ghi cùng UUID, không trừ tiền 2 lần).
Cách triển khai
Mỗi delivery có header X-Zorio-Delivery: <UUID>. Receiver lưu UUID vào Redis với TTL 24h:
const seen = await redis.set(`zorio:delivery:${deliveryId}`, '1',
'NX', 'EX', 86400);
if (seen === null) {
// Đã xử lý rồi → trả 200 và bỏ qua
return res.status(200).send('Duplicate');
}
// Xử lý event...Kết quả: dù Zorio retry bao nhiêu lần, business logic chỉ chạy 1 lần.
Tốc độ + concurrency
- Zorio gửi event song song lên đến 20 connection đồng thời per receiver URL.
- Trong burst (vd khi import 10.000 lead), receiver có thể nhận ~200-500 req/s. Hãy chuẩn bị throughput tương ứng.
- Nếu receiver không scale kịp → trả HTTP 503 với header
Retry-After: <giây>. Zorio sẽ tôn trọng header này (delay lần retry kế tiếp ≥ giá trị bạn nêu).
Khi nào webhook tự ngưng (suspended)?
Nếu webhook URL bị fail liên tục 50 event không có bất kỳ event nào thành công → hệ thống auto-suspend webhook để tránh waste resources.
- Admin sẽ nhận notification trong Admin Console.
- Cần kích hoạt lại tay sau khi fix receiver.