Standard Webhooks là đặc tả mở mô tả cách gửi và ký webhook để mọi bên nhận dùng chung một cách kiểm tra. Mỗi yêu cầu mang ba header: webhook-id, webhook-timestamp và webhook-signature.
Ba header
webhook-id: mã duy nhất của sự kiện. Gửi lại cùng sự kiện giữ nguyên mã này.webhook-timestamp: thời điểm gửi theo giây Unix.webhook-signature: chữ ký HMAC-SHA256 trên chuỗi gồm mã, thời điểm và thân yêu cầu, mã hoá base64, có tiền tố phiên bảnv1,.
Cách kiểm chữ ký
- Lấy thân yêu cầu gốc, chưa phân tích JSON.
- Ghép
webhook-id,webhook-timestampvà thân yêu cầu theo đúng thứ tự của đặc tả. - Tính HMAC-SHA256 với khoá ký, rồi đối chiếu với chữ ký trong header bằng hàm chạy trong thời gian cố định.
- Từ chối yêu cầu có thời điểm lệch quá xa thời gian hiện tại.
Phần lớn ngôn ngữ đã có thư viện Standard Webhooks làm sẵn các bước này.
Vì sao dùng chuẩn chung
Bên nhận không phải viết bộ kiểm chữ ký riêng cho từng nhà cung cấp, và dùng lại thư viện đã được kiểm tra. Cách xử lý mã sự kiện và thời điểm cũng thống nhất.
Trong Dòng Tiền Pro
Mọi webhook của Dòng Tiền Pro theo Standard Webhooks, có nhật ký giao hàng và gửi lại. SDK chính thức cho TypeScript (@dongtien/sdk) và Python (dongtien) dùng cùng cách kiểm này.
Câu hỏi thường gặp
Khoá ký có thể đổi không?
Có. Khi đổi khoá, cập nhật khoá mới ở máy chủ của bạn trước khi bỏ khoá cũ để không lỡ sự kiện.
Có cần dùng HTTPS không?
Có. Chữ ký chống giả mạo, còn HTTPS bảo vệ nội dung trên đường truyền.
