Webhook ký HMAC cho vòng đời off-ramp.
Khi sản phẩm của bạn cần trạng thái vòng đời bất đồng bộ, hãy đăng ký endpoint webhook và xác minh mỗi lần phân phối. Chữ ký ràng buộc timestamp với raw body chính xác để bạn có thể từ chối các payload bị giả mạo hoặc phát lại.
Sự kiện vòng đời
| Sự kiện | Ý nghĩa |
|---|---|
| deposit.created | Một deposit của người bán đã được tạo trên Base |
| deposit.partially_filled | Một deposit được khớp một phần |
| deposit.filled | Một deposit được khớp hoàn toàn |
| deposit.closed | Người bán đã đóng hoặc rút số dư còn lại |
| otc.taken | Một deposit OTC riêng tư đã được người mua được phê duyệt nhận |
Xác minh mọi lần phân phối
- 1Đọc header X-Usdctofiat-Signature ở dạng t=<unix>,v1=<hex>.
- 2Dựng payload đã ký dưới dạng chuỗi timestamp.rawBody bằng body thô, chưa phân tích.
- 3Tính HMAC-SHA256 trên payload đó với khóa bí mật của endpoint.
- 4So sánh theo thời gian hằng số với giá trị v1 hex trước khi tin tưởng sự kiện.
- 5Tùy chọn từ chối các lần phân phối có timestamp cũ hơn khung thời gian bạn chọn.
Bảo vệ chống phát lại là lựa chọn của bạn
Bộ nhận tham chiếu trong kho mẫu khởi đầu coi các timestamp cũ hơn 5 phút là lỗi thời để phòng chống phát lại. Khung thời gian đó được thực thi bởi bộ xác minh của bạn, không phải bên gửi, nên bạn có thể siết chặt hoặc nới lỏng tùy theo độ trễ và mức chấp nhận thử lại.
Vì chữ ký bao trùm timestamp.rawBody, hãy chỉ phân tích JSON sau khi kiểm tra HMAC thành công. Xác minh đối tượng đã phân tích thay vì các byte thô là cách phổ biến nhất khiến việc xác minh chữ ký bị sai một cách tinh vi.
Đăng ký và vận hành
- Đăng ký endpoint bằng API key Peerlytics của bạn; một khóa xác thực cho cả bề mặt offramp và Peerlytics.
- Các endpoint gặp nhiều lần phân phối thất bại liên tiếp có thể bị vô hiệu hóa cho đến khi bạn khắc phục.
- Dùng bộ nhận trong kho mẫu khởi đầu như một tham chiếu xác minh HMAC đã được kiểm chứng.
- Coi webhook như gợi ý về trạng thái; đối soát với sự thật onchain bằng deposits() khi điều đó quan trọng.
Keep exploring
Common questions
Webhook của USDCtoFiat được ký như thế nào?
Mỗi lần phân phối mang theo X-Usdctofiat-Signature: t=<unix>,v1=<hex>, một HMAC-SHA256 trên chuỗi timestamp.rawBody. Hãy tính lại HMAC bằng khóa bí mật của endpoint trên body thô và so sánh theo thời gian hằng số trước khi tin tưởng sự kiện.
Làm sao để ngăn webhook bị phát lại?
Từ chối các lần phân phối có timestamp đã ký cũ hơn khung thời gian bạn chọn. Bộ nhận tham chiếu dùng 5 phút. Bên gửi không thực thi khung thời gian, nên đây là trách nhiệm của bộ xác minh của bạn.
Tôi có cần API key cho webhook không?
Có. Việc tạo deposit không cần cấp phép, nhưng đăng ký endpoint webhook thì cần một API key của Peerlytics. Khóa đó cũng xác thực cho API của Peerlytics.