Webhook gửi nhiều lần: làm sao chỉ xử lý một lần?

Ưu tiên event hoặc delivery ID do nhà cung cấp phát hành, ví dụ Stripe Event ID hoặc X-GitHub-Delivery. Để tránh va chạm giữa tenant và nguồn, lưu khóa theo dạng (provider, endpoint, tenant_id, event_id). Không dùng riêng email, timestamp theo giây hoặc n8n execution ID: chúng có thể thay đổi giữa các lần gửi hoặc không đại diện cho cùng một nghiệp vụ.

Nếu nguồn không có event ID, xây khóa tổng hợp từ các trường bất biến, chẳng hạn (source, event_type, object_id, object_version). Chỉ dùng hash payload khi đã canonicalize JSON, vì thay đổi thứ tự field hoặc metadata không quan trọng có thể tạo hash khác. Với semantic duplicate, như hai event riêng đều báo cùng invoice đã thanh toán, business key (invoice_id, operation=mark_paid) cần bảo vệ side effect ngay cả khi event IDs khác nhau. Lưu thêm payload hash để phát hiện trường hợp cùng key nhưng nội dung bất ngờ thay đổi; đừng đưa dữ liệu nhạy cảm trực tiếp vào key.

Tạo bảng webhook_inbox có các trường tối thiểu: provider, tenant_id, event_id, event_type, payload_hash, status, attempt_count, lease_until, received_at, completed_at, result_ref và last_error. Đặt unique constraint trên bộ khóa idempotency. Khi nhận webhook, dùng một câu lệnh atomic như:

INSERT INTO webhook_inbox
  (provider, tenant_id, event_id, event_type, payload_hash, status)
VALUES ($1, $2, $3, $4, $5, 'received')
ON CONFLICT (provider, tenant_id, event_id) DO NOTHING
RETURNING id;

Có id trả về nghĩa là execution đã claim được event. Không có dòng trả về nghĩa là duplicate; workflow đọc trạng thái hiện tại rồi phản hồi an toàn, không chạy lại side effect. PostgreSQL xác nhận ON CONFLICT dùng unique index làm trọng tài và DO UPDATE có kết quả atomic ngay cả khi concurrency cao. Đây là khác biệt quan trọng so với SELECT trước rồi INSERT sau.

Trong n8n, workflow nhận nên giữ ngắn: Webhook → kiểm tra method/content type → xác thực HMAC trên raw body theo tài liệu của provider → kiểm tra timestamp chống replay → chuẩn hóa identity → PostgreSQL atomic insert → Respond to Webhook. Chỉ trả 2xx sau khi event đã được lưu bền vững. Event mới được dispatcher hoặc worker workflow lấy theo inbox_id; duplicate đã tồn tại cũng nhận phản hồi thành công nếu payload hợp lệ để nguồn không retry vô ích.

Không dựa vào static workflow data, cache trong memory hoặc lịch sử execution làm nguồn sự thật khi có nhiều replica/worker. Queue mode giúp n8n phân phối workflow executions, nhưng không tự tạo idempotency cho nghiệp vụ. Với tải thấp, receiver có thể gọi sub-workflow sau khi claim; với tải lớn hoặc side effect quan trọng, dùng inbox/job table bền vững, claim bằng lease và giới hạn concurrency theo database cùng API đích. Tách payload thô khỏi log hiển thị nếu nó chứa dữ liệu cá nhân hoặc secret.

Giả sử workflow đã tạo invoice ở hệ thống đích nhưng crash trước khi cập nhật inbox thành completed. Lease hết hạn, worker khác retry và tạo invoice thứ hai. Để đóng khoảng trống này, hãy truyền cùng idempotency key vào API đích nếu API hỗ trợ; Stripe là ví dụ về API lưu kết quả theo key và trả lại kết quả đó cho request lặp. Nếu hệ thống đích thuộc quyền kiểm soát của bạn, đặt unique constraint trên business key như (tenant_id, source_order_id, operation_version).

Nếu không thể làm side effect idempotent, cần operation ledger hoặc transactional outbox. Ghi quyết định nghiệp vụ và outbox trong cùng transaction; publisher gửi message, lưu external reference rồi đánh dấu. Consumer vẫn phải idempotent vì publisher cũng có thể gửi lại. Với email hoặc thông báo không hỗ trợ key, lưu notification_key, provider message ID và chỉ cho một worker claim; sau timeout không rõ kết quả, chuyển sang trạng thái unknown để reconciliation thay vì gửi lại ngay.

Dùng state machine rõ ràng: received → processing → completed; lỗi tạm thời chuyển retryable_failed, lỗi dữ liệu hoặc quyền chuyển dead_lettered, còn kết quả downstream không xác định chuyển unknown. Khi worker claim, đặt lease_until; nếu worker chết, event chỉ được reclaim sau khi lease hết hạn. Attempt phải có trần, exponential backoff và jitter. Không retry vô hạn lỗi 4xx do dữ liệu sai.

Duplicate đến khi trạng thái completed chỉ cần trả acknowledgment và có thể trả result_ref nội bộ. Nếu đang processing với lease còn hiệu lực, không khởi chạy worker thứ hai. Nếu retryable_failed đã đến next_attempt_at, một worker có thể claim lại bằng update có điều kiện. Thời gian giữ idempotency record phải dài hơn cửa sổ redelivery thực tế và yêu cầu audit của nghiệp vụ; không xóa theo một TTL ngắn tùy ý. Khi event cũ đến muộn, so sánh object version hoặc lấy trạng thái hiện tại từ source trước khi cập nhật.

Xác thực signature bằng secret riêng cho từng endpoint/tenant, so sánh constant-time và kiểm tra timestamp theo hướng dẫn của provider. Việc dedupe không thay thế xác thực: kẻ tấn công có thể gửi một event ID mới. Giới hạn kích thước payload, chỉ nhận event type cần thiết và không ghi token hoặc raw PII vào log. Nếu cùng key xuất hiện với payload hash khác, đánh dấu conflict để điều tra thay vì coi như duplicate bình thường.

Theo dõi webhook_received_total, duplicate_total, claim_conflict_total, tuổi event chờ lâu nhất, p95 processing latency, retry theo reason, unknown và DLQ. Alert theo tỷ lệ và backlog, không chỉ theo số execution fail. Test tối thiểu gồm: gửi cùng payload tuần tự; bắn đồng thời 20 lần; timeout sau side effect; kill worker giữa chừng; redelivery khi completed; cùng key nhưng payload khác; event đến sai thứ tự; signature sai hoặc timestamp cũ. Acceptance criterion quan trọng nhất là chỉ có một business record/notification, đồng thời mọi delivery đều có audit trail.

FAQ

1. Chỉ cần kiểm tra event ID trong database trước khi xử lý có đủ không?
Không. SELECT rồi INSERT tạo race condition khi hai execution chạy đồng thời. Cần unique constraint và thao tác atomic để chỉ một execution claim được event.

2. n8n queue mode có tự chống webhook trùng không?
Không. Queue mode phân phối execution qua worker. Idempotency key, trạng thái event và side effect chống trùng vẫn phải được thiết kế riêng.

3. Nên trả 2xx trước hay sau khi xử lý xong?
Nên xác thực và lưu event bền vững trước, sau đó trả nhanh rồi xử lý bất đồng bộ. Nếu chưa lưu mà đã trả 2xx, sự cố có thể làm mất event.

4. Có thể dùng hash toàn bộ payload làm idempotency key không?
Chỉ là phương án cuối. Metadata hoặc thứ tự JSON thay đổi có thể tạo hash khác; ngược lại hai hành động hợp lệ có payload giống nhau. Ưu tiên event ID hoặc business identity có version.

5. Khi nào được xóa bảng dedupe?
Sau khi vượt cửa sổ redelivery lớn nhất của provider và đáp ứng thời gian audit/reconciliation của nghiệp vụ. TTL phải dựa trên contract thực tế, không dùng một con số chung.