Xác minh chữ ký Webhook & Tính lũy đẳng

Webhook thông báo cho backend đối tác về các thay đổi trạng thái kinh doanh bất đồng bộ. Vì việc gửi có thể được thử lại, mỗi người nhận phải xác minh chữ ký trước khi phân tích dữ liệu đáng tin cậy và phải xử lý sự kiện một cách đồng nhất.

Tiêu đề Webhook

Tiêu đề	Mô tả
Dấu thời gian X-Agent	Thời gian Unix tính bằng giây.
X-Agent-Nonce	Không có bảo vệ phát lại.
chữ ký X-Agent	HMAC-SHA256 ký.

timestamp + nonce + rawBody

Sử dụng chính xác phần thân yêu cầu thô nhận được trên HTTP khi tái tạo giá trị đã ký. Phân tích cú pháp và tuần tự hóa lại JSON trước có thể thay đổi khoảng trắng hoặc lệnh trường và tạo ra một chữ ký khác.

Quy trình xác minh

Đọc tiêu đề thời gian, nonce và chữ ký.
Ghi lại nội dung yêu cầu thô chưa chỉnh sửa.
Xây dựng timestamp + nonce + rawBody.
Tính HMAC-SHA256 với đối tác API bí mật.
So sánh chữ ký đã tính toán và nhận được bằng cách so sánh thời gian hằng số.
Áp dụng các kiểm tra thời gian tươi mới và không tái sử dụng đã được phê duyệt.
Chỉ phân tích và xử lý sự kiện sau khi xác minh thành công.

Khi có trình xác minh Agent SDK chính thức, hãy sử dụng nó thay vì duy trì mã ký độc lập.

Tính đồng nhất của lệnh

Vụ án	Xử lý
Yêu cầu chuyển ban đầu	Tạo một agentOrderNoduy nhất toàn cầu.
HTTP hội ý	Truy vấn agentOrderNo gốc trước khi tạo một mới.
Phản hồi PROCESSING	Chờ trạng thái webhook hoặc lệnh truy vấn.
Webhook lặp lại	Loại bỏ trùng lặp bằng khóa đồng tính và trạng thái cuối cùng.

Bản ghi idempotency được khuyến nghị

Lưu trữ đủ thông tin để nhận biết một lần giao hàng lặp lại và phục hồi an toàn:

Lĩnh vực	Mục đích
Khóa sự kiện hoặc khóa kinh doanh	Xác định duy nhất thông báo hoặc thao tác.
Số đơn hàng đối tác	Kết nối sự kiện với yêu cầu ban đầu.
Băm tải trọng	Giúp xác định các tải trọng lặp lại xung đột.
Trạng thái xử lý hiện tại	Phân biệt công việc nhận được, xử lý, thành công và thất bại.
Tình trạng kinh doanh cuối cùng	Ngăn một hành động cuối được áp dụng hai lần.
Dấu thời gian đã xử lý	Hỗ trợ các chính sách điều tra và lưu trữ.

Cam kết bản ghi thay đổi kinh doanh và bản ghi idempotency trong cùng một giao dịch nếu có thể. Một sự kiện lặp lại nên trả về kết quả đã biết thay vì áp dụng lại số dư, lệnh hoặc thay đổi người dùng.

Quy tắc timeout và thử lại

Thời gian chờ HTTP không chứng minh rằng yêu cầu ban đầu đã thất bại. Truy vấn thao tác bằng agentOrderNogốc, hoặc chờ webhook của nó, trước khi quyết định có cần hành động khác hay không. Tạo số lệnh doanh nghiệp mới sau mỗi lần timeout có thể gây ra các chuyển động quỹ trùng lặp.

Danh sách kiểm tra sản xuất

Xác minh chữ ký trước khi JSON phân tích cú pháp hoặc xử lý kinh doanh.
Bảo toàn phần cơ thể thô độc lập với payload đã phân tích cú pháp.
Từ chối các yêu cầu cũ hoặc phát lại theo chính sách tích hợp đã được phê duyệt.
Đảm bảo xử lý sự kiện an toàn cho việc giao hàng lặp đi lặp lại hoặc giao hàng ngoài đơn hàng.
Ghi lại ID sự kiện, số đơn hàng đối tác, kết quả xử lý và thời gian yêu cầu.
Xóa các bí mật và giá trị chữ ký khỏi nhật ký và tệp đính kèm hỗ trợ.

Bí mật & Ký HMAC

Bảo vệ bí mật API được sử dụng để xác minh yêu cầu và webhook.

Tổng quan Agent SDK

Xem xét toàn bộ quy trình tích hợp backend.

SDK Khắc phục sự cố