Event
Bản ghi về thay đổi của payment, game session, KYC check, bonus, player profile hoặc object khác.
Documentation / Webhook
Webhook và event delivery
Thiết lập việc truyền status và event đáng tin cậy giữa các hệ thống: từ tạo message và xác minh signature đến xác nhận đã nhận, redelivery và giám sát lỗi.
Event
status và thay đổi
Signature
xác minh tính xác thực
Retry
redelivery
Monitoring
lịch sử và diagnostics
Luồng event
Từ tạo đến acknowledgement
01
Tạo event
Chỉ định ID, type, time, object, status và dữ liệu liên quan.
02
Ký và gửi
Gửi event qua HTTPS kèm signature và timeout giới hạn.
03
Xác nhận đã nhận
Sau khi xác minh, lưu event và nhanh chóng trả về HTTP response thành công.
04
Retry khi có lỗi
Retry delivery với khoảng cách tăng dần và lưu các event chưa gửi được để điều tra.
Tổng quan
Webhook thông báo thay đổi trạng thái
Sender có thể retry delivery, vì vậy receiver phải xác minh nguồn, xác nhận đã nhận và chỉ áp dụng mỗi event một lần.
Acknowledgement
Receiver trả về HTTP response thành công sau khi xác minh và lưu event một cách đáng tin cậy.
Recovery
Redelivery và đối soát giúp khôi phục dữ liệu sau khi một trong hai hệ thống tạm thời không khả dụng.
Cấu trúc event
Event nên chứa những dữ liệu gì
Cấu trúc message thống nhất giúp việc xác minh, routing, bảo vệ duplicate và hỗ trợ nhiều loại event dễ dàng hơn.
Event ID
Giá trị duy nhất để hệ thống nhận biết redelivery và tìm lịch sử xử lý.
Event type
Tên rõ ràng và ổn định xác định thay đổi đã xảy ra và cách xử lý.
Thời gian tạo
Ngày và giờ event được tạo theo format và múi giờ đã thống nhất.
Object liên quan
Type và ID của payment, player, round, request, bonus hoặc object khác.
Schema version
Version number giúp thay đổi cấu trúc message an toàn mà không làm gián đoạn các tích hợp đang hoạt động.
Liên kết với giao dịch
ID của request gốc, transaction, session hoặc chuỗi hành động liên quan.
Context
Brand, project, market, environment, provider và dữ liệu khác cần thiết để routing chính xác.
Event data
Bộ field tối thiểu cần thiết để xử lý thay đổi hoặc thực hiện API request tiếp theo.
Signature và xác minh
Xác minh tính xác thực và toàn vẹn của event
Trước khi thay đổi dữ liệu, receiver xác minh kết nối an toàn, signature, thời gian tạo và event ID duy nhất.
01
Nhận raw message
Xác minh signature trên raw request body trước khi thay đổi format JSON.
02
Kiểm tra timestamp
Từ chối request nếu thời gian event nằm ngoài khoảng cho phép.
03
Xác minh signature
Sử dụng secret đã thống nhất và thuật toán HMAC hoặc digital signature.
04
Kiểm tra ID
Xác nhận event chưa được áp dụng trước đó và lưu kết quả xác minh.
Delivery và retry
HTTP response và redelivery
Sender phải phân biệt được nhận thành công, lỗi tạm thời và lỗi vĩnh viễn; receiver phải phản hồi nhanh và rõ ràng.
HTTP response thành công
Xác nhận event đã được kiểm tra và lưu an toàn để xử lý tiếp.
Timeout giới hạn
Không xử lý tác vụ dài trước khi phản hồi sender — hãy lưu event trước.
Redelivery
Retry delivery khi có lỗi mạng tạm thời, hệ thống không khả dụng hoặc không có response.
Tăng khoảng retry
Tăng dần khoảng chờ giữa các lần thử để tránh tạo thêm tải.
Queue event chưa gửi được
Khi hết số lần thử, giữ lại event để chẩn đoán và xử lý thủ công.
Redelivery thủ công
Operator có thể gửi lại event đã chọn mà không tạo giao dịch mới.
Monitoring delivery
Theo dõi số lần thử, response, lỗi gần nhất và thời gian gửi tiếp theo.
Alert
Thông báo cho team khi lỗi tăng, hết lượt retry hoặc event tích tụ trong queue.
Xử lý event
Bảo vệ duplicate và thứ tự status
Receiver không được dựa vào giả định event chỉ được gửi một lần hoặc luôn đến đúng thứ tự.
Chỉ áp dụng một lần
Lưu event ID trước khi thay đổi dữ liệu.
Xác nhận event lặp lại mà không debit, credit hoặc thay đổi trạng thái lần nữa.
Liên kết event với object và trạng thái hiện tại của object.
Lưu event và business change như một giao dịch nhất quán.
Thứ tự và tính cập nhật
So sánh timestamp, sequence number hoặc event version.
Không đưa object quay lại trạng thái cũ khi một event cũ đến trễ.
Chỉ cho phép chuyển đổi status hợp lệ.
Nếu có nghi ngờ, yêu cầu trạng thái hiện tại của object qua API.
Testing
Cần kiểm tra gì trước launch
Kiểm tra delivery thành công, signature không hợp lệ, duplicate, response chậm, event sai thứ tự và recovery sau sự cố.
Signature không hợp lệ
Message bị sửa, key không xác định, timestamp hết hạn và thuật toán không được hỗ trợ.
Redelivery
Cùng một event đến nhiều lần trước và sau khi xử lý hoàn tất.
Response chậm
Receiver phản hồi quá lâu, kết nối bị ngắt hoặc acknowledgement không đến được sender.
Xử lý sai thứ tự
Status cuối đến trước status trung gian và event cũ đến sau event mới hơn.
Endpoint không khả dụng
Kiểm tra lỗi HTTP 5xx, DNS, TLS, rate limit và trường hợp dùng hết toàn bộ số lần retry.
Lịch sử delivery
Tất cả lần thử, response, lỗi và kết quả redelivery thủ công phải có thể tìm được theo event ID.
Checklist trước launch
Production delivery được bật sau khi đã kiểm tra security, bảo vệ duplicate, redelivery và error monitoring.
Test và production environment dùng endpoint và signing secret khác nhau.
Signature được xác minh trên raw message cùng với thời gian tạo.
Event ID được lưu và bảo vệ giao dịch khỏi thực thi nhiều lần.
Receiver nhanh chóng trả về HTTP response thành công sau khi lưu event.
Đã cấu hình retry, khoảng chờ tăng dần và redelivery thủ công.
Lịch sử delivery và tìm kiếm theo ID khả dụng cho support team.
Cần thiết lập event delivery đáng tin cậy?
Cung cấp danh sách event, receiving endpoint và quy tắc chuyển status. APIACE sẽ giúp xác định cấu trúc message, xác minh signature, redelivery và error monitoring.