Thiết kế webhook không mất dữ liệu: thử lại, idempotency và cảnh báo

Tích hợp qua webhook trông đơn giản: hệ thống A gửi request, hệ thống B xử lý. Nhưng trong thực tế, mạng chập chờn, máy chủ khởi động lại và nhà cung cấp gửi lại cùng một sự kiện nhiều lần.

Nhận nhanh, xử lý sau

Endpoint webhook chỉ nên xác thực chữ ký, lưu sự kiện vào hàng đợi rồi trả về 200 ngay. Việc xử lý nặng để worker làm.

app.post('/webhooks/payment', async (req, res) => {
  verifySignature(req);
  await queue.add('payment', req.body);
  res.sendStatus(200);
});

Idempotency: xử lý hai lần vẫn đúng

Mỗi sự kiện có một ID duy nhất. Trước khi xử lý, kiểm tra ID đó đã được ghi nhận chưa. Nếu rồi, bỏ qua.

Hãy giả định mọi webhook sẽ đến ít nhất hai lần.

Thử lại có giới hạn

Khi CRM không phản hồi, worker thử lại với thời gian chờ tăng dần: 1 phút, 5 phút, 30 phút, 2 giờ. Sau số lần giới hạn, chuyển sự kiện sang hàng đợi lỗi để xem xét thủ công.

Cảnh báo đúng người, đúng lúc

Không ai đọc email lỗi số 200 trong ngày. Chỉ cảnh báo khi hàng đợi lỗi có sự kiện mới hoặc tỉ lệ thất bại vượt ngưỡng, và gửi đến kênh mà đội vận hành thực sự theo dõi.

Kết luận

Ba nguyên tắc này giúp một trung tâm đào tạo đồng bộ 100% đăng ký vào CRM trong vòng một phút, không còn nhập liệu thủ công.