Khi một hệ thống bán hàng tạo hóa đơn điện tử, trạng thái xử lý có thể thay đổi nhiều lần: tiếp nhận, chờ cấp mã, đã phát hành, bị từ chối hoặc cần điều chỉnh. Nếu chỉ gọi API để kiểm tra định kỳ, ứng dụng phải liên tục hỏi máy chủ và vẫn có nguy cơ cập nhật chậm. Webhook giúp hệ thống nhận thông báo gần như ngay lập tức, nhưng cần được thiết kế đúng để tránh mất dữ liệu hoặc xử lý trùng.
Webhook giải quyết bài toán gì?
Webhook là một HTTP endpoint do hệ thống của doanh nghiệp cung cấp để nền tảng hóa đơn gửi sự kiện đến. Mỗi khi trạng thái hóa đơn thay đổi, nền tảng gửi một request chứa mã hóa đơn, trạng thái mới, thời điểm cập nhật và mã sự kiện. Ứng dụng tiếp nhận request, kiểm tra tính hợp lệ rồi cập nhật đơn hàng hoặc màn hình quản trị.
Mô hình này phù hợp với các hệ thống cần đồng bộ nhiều hóa đơn, gửi email cho khách hàng sau khi phát hành hoặc tự động kích hoạt bước đối soát. Nếu cần thiết kế luồng kết nối sâu hơn, bạn có thể tham khảo hướng dẫn API hóa đơn điện tử Pay2S và các nguyên tắc bảo vệ token khi tích hợp.
1. Chuẩn hóa dữ liệu trạng thái
Không nên để mỗi module tự hiểu trạng thái theo một cách khác nhau. Hãy quy định một bộ trạng thái nội bộ và ánh xạ rõ ràng từ dữ liệu nhận được:
- received: hệ thống đã nhận yêu cầu tạo hóa đơn;
- processing: hóa đơn đang được xử lý;
- issued: hóa đơn đã phát hành thành công;
- rejected: yêu cầu bị từ chối, cần đọc thêm mã lỗi;
- cancelled: hóa đơn đã bị hủy hoặc thay thế.
Nên lưu cả trạng thái gốc, mã lỗi, nội dung lỗi và thời điểm nhận sự kiện. Việc này giúp kiểm tra lại khi người dùng phản ánh hóa đơn chưa cập nhật.
2. Xác thực request trước khi ghi nhận
Endpoint webhook phải dùng HTTPS và không nên tin ngay dữ liệu gửi đến. Tùy khả năng của nền tảng, có thể áp dụng chữ ký HMAC, token riêng cho từng môi trường hoặc danh sách IP được phép. Chữ ký cần được kiểm tra trên đúng chuỗi nội dung gốc, trước khi JSON được biến đổi.
Ngoài xác thực, hãy giới hạn kích thước request, kiểm tra kiểu dữ liệu và từ chối các trường bắt buộc bị thiếu. Endpoint cũng nên ghi log mã sự kiện, không ghi mật khẩu, access token hay toàn bộ thông tin nhạy cảm của khách hàng.
3. Chống xử lý trùng bằng idempotency
Webhook có thể được gửi lại khi mạng chập chờn hoặc hệ thống nhận phản hồi muộn. Vì vậy, xử lý cùng một sự kiện hai lần không được tạo ra hai email, hai lần cập nhật doanh thu hoặc hai bản ghi hóa đơn.
nếu event_id đã tồn tại:
trả về HTTP 200
ngược lại:
lưu event_id
cập nhật trạng thái trong một transaction
trả về HTTP 200Khóa duy nhất nên đặt ở event_id. Nếu nền tảng không cung cấp mã sự kiện, có thể tạo khóa từ mã hóa đơn, trạng thái và thời điểm cập nhật, nhưng cần kiểm tra kỹ để không loại nhầm một lần thay đổi hợp lệ.
4. Retry và hàng đợi xử lý
Endpoint nên trả lời nhanh sau khi đã xác thực và lưu sự kiện. Phần đồng bộ sang CRM, gửi email hoặc cập nhật báo cáo nên được đưa vào hàng đợi. Khi dịch vụ nội bộ tạm thời lỗi, hệ thống có thể retry theo cấp số nhân:
| Lần thử | Khoảng chờ gợi ý |
|---|---|
| 1 | 30 giây |
| 2 | 2 phút |
| 3 | 10 phút |
Sau số lần retry tối đa, chuyển sự kiện vào danh sách cần xử lý thủ công. Không nên retry vô hạn vì một sự kiện lỗi dữ liệu sẽ làm đầy hàng đợi.
5. Luôn có quy trình đối soát
Webhook giúp cập nhật nhanh nhưng không nên là nguồn kiểm tra duy nhất. Hãy chạy một tác vụ đối soát định kỳ để lấy các hóa đơn phát sinh trong khoảng thời gian gần đây, so sánh với dữ liệu nội bộ và bổ sung những sự kiện bị thất lạc. Khi tích hợp với nền tảng như Pay2S, cách làm này giúp phát hiện sớm lỗi mạng, lỗi xác thực hoặc thay đổi cấu hình endpoint. Bạn có thể xem thêm quy trình đối soát hóa đơn điện tử để xây dựng checklist vận hành.
Quy trình triển khai đề xuất
- Tạo endpoint riêng cho môi trường thử nghiệm và môi trường thật.
- Xác thực request, kiểm tra schema và lưu event log.
- Cập nhật trạng thái bằng transaction và khóa idempotency.
- Đưa các tác vụ phụ vào queue, có retry và dead-letter queue.
- Thiết lập cảnh báo khi tỷ lệ lỗi hoặc số sự kiện chờ vượt ngưỡng.
- Chạy đối soát định kỳ để đảm bảo dữ liệu nội bộ khớp với nền tảng.
Kết luận
Webhook là cách hiệu quả để đồng bộ trạng thái hóa đơn điện tử theo thời gian gần thực. Ba nguyên tắc quan trọng nhất là xác thực request, xử lý idempotent và có đối soát định kỳ. Khi triển khai đúng, doanh nghiệp vừa giảm số lần gọi API vừa hạn chế lỗi trùng, mất trạng thái và gửi thông báo sai cho khách hàng.
Lưu ý: Hãy thử nghiệm toàn bộ luồng với dữ liệu mẫu trước khi bật endpoint cho môi trường thật và bảo vệ riêng thông tin xác thực của từng hệ thống.
