Webhook đến sau không nhất thiết mô tả trạng thái mới hơn. Nếu website nhận thông báo “đơn đã hủy” rồi mới nhận bản gửi lại của “đơn đang chuẩn bị”, ghi đè theo thứ tự nhận có thể đưa đơn về trạng thái cũ. Cách xử lý cần tách ba việc: xác thực sự kiện, xác định dữ liệu có thẩm quyền và quyết định chuyển trạng thái.
Hướng dẫn này dành cho người phụ trách tích hợp website với hệ thống nghiệp vụ. Đây là phương án thiết kế và bộ tình huống giả định để trao đổi với đội phát triển, không phải một tính năng đã tích hợp sẵn trên mọi website Onter.
Phân biệt sự kiện trùng với sự kiện cũ
Hai lần giao cùng một sự kiện là vấn đề khử trùng. Hai sự kiện khác nhau của cùng một đơn, đến đảo thứ tự, là vấn đề thứ tự và trạng thái. Chặn event ID trùng không tự giải quyết được trường hợp thứ hai.
Tài liệu webhook Stripe nêu rõ sự kiện không được bảo đảm giao theo thứ tự phát sinh; timestamp ở độ phân giải giây cũng không đủ để xếp thứ tự tất cả sự kiện. Đây là đặc tính của nguồn được dẫn, không phải quy luật rằng mọi nhà cung cấp dùng cùng payload hoặc version.
Một đơn hàng, ba thông báo đến không theo thứ tự
Ví dụ giả định dưới đây dùng mã đơn DH-017 và version do hệ thống nguồn cung cấp. Chỉ áp dụng phép so version khi nguồn công bố version có thứ tự cho đúng đối tượng; không tự thay bằng giờ máy nhận.
| Lần nhận | Dữ liệu nhận | Quyết định dự kiến |
|---|---|---|
| 1 | EV-3, version 3, đã hủy | Đọc trạng thái nguồn và kiểm điều kiện hủy trước khi ghi |
| 2 | EV-2, version 2, đang chuẩn bị | Không hạ version 3 về 2; lưu lý do bỏ qua |
| 3 | EV-3 được giao lại | Nhận diện event đã xử lý; không thực hiện tác động lần nữa |
Nếu nguồn không có version đáng tin, đưa sự kiện vào hàng chờ đối soát và đọc lại đối tượng bằng API được cấp quyền. Kết quả đọc có thể còn trễ hoặc thất bại; không đủ bằng chứng thì giữ trạng thái chờ, không đoán trạng thái cuối.
Hợp đồng cập nhật cần ghi rõ trước khi viết handler
- Danh tính: event ID, object ID và tenant/tài khoản nguồn phải được phân biệt.
- Tính mới: dùng version/sequence chính thức hoặc quy trình đọc nguồn, không mặc định timestamp là sequence.
- Chuyển trạng thái: những bước nào được phép, bước nào cần người xử lý; hoàn tiền hay đổi đơn là sự kiện nghiệp vụ khác, không chỉ “quay lại trạng thái cũ”.
- Đồng thời: cập nhật có điều kiện theo version đang lưu; khóa hoặc cơ chế tương đương phải nằm trong thiết kế, không chỉ kiểm ở đầu handler.
- Tác động ngoài: gửi email, giao hàng hay tạo bản ghi phải có dấu vết riêng; lưu trạng thái đơn thành công chưa chứng minh tác động ngoài đã hoàn tất.
Chữ ký và quyền nguồn cần được kiểm trước khi tin nội dung. Theo hướng dẫn Stripe, việc xác minh chữ ký cần raw body đúng cách. Mỗi nhà cung cấp có quy trình riêng; không áp một header mẫu cho tất cả kết nối.
Bốn ca nên đưa vào nghiệm thu
- Sự kiện mới đến trước sự kiện cũ: trạng thái không bị ghi lùi.
- Hai worker đọc cùng một version: chỉ cập nhật hợp lệ thắng, worker còn lại đối soát lại.
- API nguồn không phản hồi: event còn dấu vết chờ, không bị đánh dấu đã xử lý thành công.
- Ghi trạng thái xong nhưng gửi thông báo lỗi: phục hồi phần thông báo không lặp tác động nghiệp vụ đã hoàn tất.
Ghi kết quả bằng object ID, event ID, version trước/sau, quyết định và receipt tác động ngoài. Không đưa toàn bộ payload khách hàng vào log nếu chỉ cần vài trường tra soát. Bộ ca này khác với việc bấm retry cho một tác vụ đã timeout: nó kiểm việc nhận nhiều thay đổi của cùng một đối tượng.
Từ sơ đồ tích hợp đến phạm vi triển khai
Trước khi trao đổi một quy trình tự động hóa có kiểm soát, hãy chuẩn bị tài liệu sự kiện của nguồn, trạng thái nghiệp vụ và các tác động cần bảo vệ. Nếu bước cuối có AI hoặc người duyệt, liên kết quyết định với đúng phiên bản dữ liệu theo hướng dẫn human in the loop.
Muốn kiểm tra luồng tích hợp của doanh nghiệp, bạn có thể trao đổi bài toán với Onter. Phạm vi, quyền truy cập và cách nghiệm thu cần được xác nhận trước khi triển khai; bài viết không cam kết tương thích sẵn với một nền tảng cụ thể.
