Webhook Xác minh chữ ký & quyền sở hữu

Trang này theo dõi Agent Java SDK WEBHOOKS.md tại cam kết fa6c7b6. Đây chỉ là bản cập nhật tài liệu; không có tạo phẩm SDK mới nào chứa các phương thức trợ giúp cảnh báo được phát hành.

Tất cả bốn loại sự kiện đều sử dụng một lệnh gọi lại của người bán URL và được gửi đi bởi nội dung event. Nhìn thấy Webhook Sự kiện & Cảnh báo thanh lý cho các trường sự kiện và ví dụ về tải trọng.

tiêu đề Webhook

timestamp + nonce + rawBody

sự kiện bình thường

Liên tục loại bỏ trùng lặp trong phạm vi người bán và environment, một cách nguyên tử với quá trình xử lý kinh doanh. Các giá trị notificationId khác nhau xác định các thông báo FIRST / UPGRADE / REMINDER độc lập; không loại bỏ thông báo bằng cách nhóm theo người dùng, tập hoặc eventType. Không thể sử dụng khóa tạm thời trống để loại bỏ trùng lặp. SDK chỉ trả về khóa trợ giúp; nó không tồn tại hoặc xử lý dữ liệu kinh doanh. Ghi nhận cùng một danh tính với một cơ thể khác là xung đột; không ghi đè lên phần thân đã được xử lý.

Xác minh và nhận chữ ký

Sử dụng bí mật thương mại API để tính toán HMAC-SHA256 chữ ký thập lục phân của timestamp + nonce + rawBody. Xác minh các byte nhận được ban đầu; trước tiên không định dạng JSON, đổi tên các trường hoặc sắp xếp lại phần nội dung.

Trước tiên, hãy xác minh chữ ký, sau đó kiểm tra khoảng thời gian (khuyến nghị ±300 giây), người bán và môi trường. Tiếp theo, trích xuất danh tính bình thường và xử lý thông báo một cách đáng tin cậy. Bảo toàn các giá trị sự kiện chưa biết để chẩn đoán; không bao giờ hiểu chúng là sự thành công của quỹ. Trình trợ giúp xác minh không thực hiện kiểm tra thời gian, quyền sở hữu hoặc kiểm tra loại bỏ trùng lặp liên tục.

Trả về HTTP 2xx sau khi hoàn tất xử lý hoặc xác nhận một bản sao giống hệt nhau; trả về không phải 2xx khi thất bại. Người gửi cảnh báo có thời gian chờ HTTP là 5 giây và có tối đa 8 lần thử. Thử lại giữ lại cơ thể đông lạnh; chỉ có dấu thời gian chữ ký và thay đổi nonce. Trả lời kịp thời sau khi chấp nhận đáng tin cậy; công việc kinh doanh lâu dài có thể sử dụng các nhiệm vụ thường xuyên của chính thương gia.

Thông báo của người bán không phụ thuộc vào trạng thái trực tuyến của người dùng. Các lần đẩy của người dùng nền tảng chỉ được thực hiện trực tuyến với nỗ lực tốt nhất, không có tính năng phát lại ngoại tuyến; giai đoạn một không có hộp thư thông báo.

Phản hồi thành công và ngừng thử lại

Lệnh gọi lại và cảnh báo thanh lý quỹ sử dụng chỉ mã trạng thái HTTP để xác định giao hàng thành công. Người gửi không diễn giải nội dung phản hồi code, success, result hoặc message và không yêu cầu phản hồi OK / success cố định.

Nội dung phản hồi có thể trống, văn bản hoặc JSON. Các trường ví dụ result là thông tin dành cho người bán, không phải là yêu cầu về giao thức. 202 Accepted cũng dừng việc thử lại nền tảng, vì vậy chỉ trả lại thông báo sau khi lưu thông báo vào hàng đợi tác vụ liên tục của người bán một cách đáng tin cậy, chứ không chỉ bắt đầu một tác vụ không đồng bộ trong bộ nhớ.

Ví dụ phản hồi thành công

Sau khi quá trình xử lý công việc hoàn tất hoặc thông báo đã được lưu một cách đáng tin cậy vào hàng đợi chờ xử lý của chính người bán:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"RECEIVED"}

Khi không cần nội dung phản hồi:

HTTP/1.1 204 No Content

Đối với thông báo đã được xử lý có nội dung giống hệt nhau, hãy bỏ qua quá trình xử lý công việc trùng lặp và vẫn trả về 2xx:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"DUPLICATE"}

Ví dụ về phản hồi lỗi

Nếu cơ sở dữ liệu tạm thời không khả dụng và người bán chưa hoàn tất quá trình xử lý cũng như chưa lưu thông báo một cách đáng tin cậy, hãy trả về non-2xx để nền tảng có thể thử lại:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{"result":"FAILED","message":"temporary storage failure"}

Từ chối chữ ký không hợp lệ mà không cập nhật dữ liệu kinh doanh hoặc hồ sơ chống trùng lặp thành công:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"result":"INVALID_SIGNATURE"}

Các cơ quan phản hồi này không thay đổi quyết định thử lại. Đừng mong đợi lỗi 401 hoặc 409 sẽ ngừng thử lại vĩnh viễn; điều tra chữ ký, nội dung thông báo hoặc cấu hình người bán.

Ví dụ không chính xác: phản hồi sau vẫn được tính là gửi thành công. Nền tảng sẽ không thử lại vì success:false.

HTTP/1.1 200 OK
Content-Type: application/json
{"success":false,"code":500,"message":"processing failed"}

Nếu khung hoặc trình xử lý ngoại lệ chung bao gồm các lỗi kinh doanh trong HTTP 200, hãy đặt rõ ràng trạng thái lỗi chính xác ở điểm cuối gọi lại.

Xác nhận đáng tin cậy và phân phối trùng lặp

Lệnh đề xuất: xác minh chữ ký và kiểm tra thời gian/người bán/môi trường → trích xuất danh tính bình thường → xử lý dữ liệu kinh doanh và bản ghi chống trùng lặp thành công trong giao dịch hoặc lưu một cách đáng tin cậy một nhiệm vụ đang chờ xử lý → trả về 200/204 sau khi cam kết thành công. Không trả về 2xx hoặc đánh dấu thông báo đã xử lý trước khi ghi cơ sở dữ liệu thành công.

Việc phân phối trùng lặp vẫn có thể xảy ra sau khi quá trình xử lý của người bán thành công: phản hồi có thể bị mất hoặc nền tảng có thể nhận được 2xx nhưng không tồn tại được SUCCESS. Lệnh gọi lại HTTP không đảm bảo giao hàng một lần. Liên tục loại bỏ trùng lặp trong phạm vi người bán và environment. Quỹ sử dụng orderType:orderId:targetStatus; cảnh báo sử dụng liquidation.warning:notificationId. Đối với nội dung giống hệt đã được xử lý, hãy trả lại 2xx mà không ghi có tiền hoặc đưa ra lời nhắc lại. Đối với cùng một danh tính với một nội dung khác, hãy ghi lại xung đột và trả về không phải 2xx; không ghi đè lên bản ghi gốc.

Xác nhận thành công có nghĩa là người bán đã nhận được/xử lý thông báo chứ không phải hoạt động nạp tiền đã thành công. Sau khi ghi lại thông báo về số tiền hợp lệ bằng targetStatus=FAILED, đồng thời trả về 2xx; lỗi đơn hàng không phải là lý do để từ chối xác nhận thông báo.

Ranh giới tài trợ và môi trường

Luồng chuyển giao Hợp đồng ban đầu webhook và queryOrder không tự động áp dụng cho Tài trợ. Xác nhận hoạt động cấp vốn bằng cách sử dụng queryWalletTransfer và môi trường đặt hàng ban đầu. Nguồn tài trợ sử dụng status; Phản hồi chuyển nhượng hợp đồng ban đầu sử dụng orderStatus. Phản hồi HTTP thành công hoặc code=0 bản thân nó không chứng minh được tiền đã được chuyển.

Thông báo chuyển giao Hợp đồng được mô phỏng rõ ràng bao gồm environment=SIMULATED. Trước tiên, hãy xác minh nội dung thô, sau đó kiểm tra người dùng, số lượng, danh tính đơn hàng và môi trường đối với đơn hàng kinh doanh địa phương đã lưu.

Hướng dẫn thu hồi vốn · Hướng dẫn môi trường