Xác minh chữ ký webhook

Xác minh chữ ký HMAC, kiểm tra timestamp và xử lý webhook trùng lặp.

1 phút đọc5 phần

Giữ nguyên raw body

Xác minh trên bytes body nhận được, trước khi parse rồi stringify lại. Chỉ một thay đổi khoảng trắng cũng có thể làm chữ ký khác đi. Chọn cách lấy raw body phù hợp với framework backend của bạn.

Các header cần biết

Header	Ý nghĩa
`Tembuilder-Event`	Loại sự kiện, ví dụ `renders.status`
`Tembuilder-Delivery-Id`	Định danh lần giao
`Tembuilder-Attempt`	Lần thử
`Tembuilder-Timestamp`	Unix timestamp theo giây
`Tembuilder-Signature`	`v1=` cộng HMAC-SHA256 dạng hex

Signing secret hiển thị khi tạo endpoint là base64url không padding; decode để lấy bytes secret trước khi tính HMAC.

Nội dung được ký

Chuỗi ký là bytes UTF-8 của timestamp, dấu chấm, rồi raw body bytes:

timestamp + "." + raw_body

Tính HMAC-SHA256 bằng bytes secret; so sánh với chữ ký bằng hàm constant-time, không dùng so sánh string thông thường cho secret MAC.

Timestamp và thông báo lặp

Receiver nên áp dụng một cửa sổ thời gian chấp nhận, ví dụ ±5 phút nếu phù hợp đồng hồ và quy trình của bạn. Đây là khuyến nghị receiver, không phải thời hạn cam kết giao của Tembuilder.

Lưu delivery ID để nhận biết retry trùng. Xử lý trạng thái theo render ID và logic nghiệp vụ, không giả định mọi notification đến đúng thứ tự hoặc chỉ đến một lần.

Thử trước khi dùng thật

Gửi test, kiểm tra chữ ký đúng; sửa một byte của body và bảo đảm bị từ chối; thử timestamp cũ và cùng delivery hai lần. Không ghi secret/raw payload nhạy cảm vào log hỗ trợ.