Xác minh chữ ký webhook: nguyên tắc và cấu hình Mailera

HMAC xác minh điều gì?

Điểm nhận webhook cần quyết định có chấp nhận yêu cầu hay không trước khi cập nhật dữ liệu hoặc gọi agent. Đừng để thao tác nghiệp vụ chạy trước rồi mới kiểm tra chữ ký.

Theo RFC 2104 về HMAC, HMAC là cơ chế xác thực thông điệp bằng hàm băm mật mã và khoá bí mật. Bên nhận dùng bí mật cùng dữ liệu cần xác minh để tính lại mã xác thực, rồi so sánh với mã nhận được.

HMAC phục vụ xác thực và kiểm tra toàn vẹn, không mã hoá nội dung. Vì vậy, hãy dùng điểm nhận HTTPS và coi xác minh chữ ký là một bước riêng trong quá trình tiếp nhận email. Hướng dẫn xác minh webhook của GitHub cũng đặt việc kiểm tra chữ ký trước các bước xử lý tiếp theo; định dạng chữ ký của từng nhà cung cấp phải được triển khai riêng.

Cần chuẩn bị gì cho webhook Mailera?

Dùng hộp thư thử do bạn kiểm soát, đã kết nối với Mailera, và chọn sự kiện message.received. Mailera không tạo hộp thư hay địa chỉ email mới: sản phẩm kết nối các hộp thư bạn đang có. Bạn có thể xem cách Mailera kết nối hộp thư hoặc làm theo hướng dẫn kết nối hộp thư đầu tiên.

Có hai loại bí mật cần tách rõ:

REST API dùng base URL https://mailera.app/api/public/v1 và header Authorization: Bearer $MAILERA_API_KEY. Đây là thông tin xác thực khi bạn gọi API, không phải công thức xác minh yêu cầu gửi tới điểm nhận.

Để chuẩn bị:

1. Mở Cài đặt, vào phần API key và chọn Tạo key. Khoá dùng quản lý webhook cần quyền API webhooks.
2. Tạo webhook bằng POST /webhooks, đối chiếu cấu trúc yêu cầu trong tài liệu API Mailera.
3. Lưu bí mật ký vào nơi quản lý bí mật ngay khi nhận phản hồi. Mailera chỉ trả bí mật này một lần, lúc tạo webhook.
4. Giữ bí mật ký ngoài mã nguồn và nhật ký. Không đưa bí mật vào kho mã hoặc ảnh chụp cấu hình.

Các thao tác liệt kê, tạo, sửa và xoá webhook đều yêu cầu quyền webhooks. PATCH /webhooks/{id} cho phép bật hoặc tắt webhook, đổi sự kiện hoặc URL. Phần Mailera dành cho lập trình viên là điểm bắt đầu nếu bạn đang ghép REST API với webhook trong cùng ứng dụng.

Những header nào cần nhận diện?

Mailera liệt kê các tên header sau:

Không suy ra thuật toán ký từ tên header. Với hai tên header chữ ký, không tự coi chúng là tương đương, đặt thứ tự ưu tiên hoặc viết logic thử lần lượt rồi chấp nhận giá trị nào khớp.

Nguyên tắc chung: xác minh HMAC trong Node.js

Phần này giải thích cách tổ chức bộ xác minh cho một giao thức dùng HMAC theo RFC 2104, độc lập với cấu hình webhook Mailera ở trên.

Node.js cung cấp crypto.createHmac(algorithm, key[, options]); xem tài liệu Crypto của Node.js. Hàm này tính HMAC, còn giao thức ứng dụng quyết định thuật toán, khoá và dữ liệu đầu vào.

Một bộ xác minh HMAC cần thực hiện các bước sau:

1. Giữ dữ liệu cần xác minh. Nếu giao thức ký phần thân nguyên bản, giữ phần thân dạng byte trước bước phân tích JSON. Không phân tích rồi tuần tự hoá lại để thay cho dữ liệu gốc.
2. Kiểm tra đầu vào. Kiểm tra sự hiện diện và định dạng của các thành phần mà giao thức yêu cầu. Đừng dùng giá trị mặc định để tiếp tục khi thiếu dữ liệu xác minh.
3. Tính lại HMAC. Dùng khoá bí mật, hàm băm và biểu diễn thông điệp mà giao thức quy định. HMAC không tự quyết định cách ghép timestamp, phần thân hay dấu phân cách.
4. Giải mã và so sánh mã xác thực. Kiểm tra định dạng và độ dài trước phép so sánh. Dùng phương thức dành cho dữ liệu mật mã, chẳng hạn crypto.timingSafeEqual, thay vì so sánh chuỗi bằng toán tử bằng.
5. Chỉ chuyển tiếp sau khi kiểm tra thành công. Kiểm tra cấu trúc sự kiện trước khi cho phép thực hiện nghiệp vụ.

GitHub khuyến nghị không dùng phép so sánh thông thường cho chữ ký và không sửa payload hoặc header trước khi xác minh. Có thể áp dụng các nguyên tắc này khi thiết kế bộ xác minh, nhưng công thức ký của GitHub chỉ dành cho giao thức của GitHub.

Trong nhật ký, ưu tiên ghi bước thất bại và loại lỗi thay vì bí mật ký hoặc toàn bộ nội dung thư. Thiết kế nhánh từ chối sao cho nó kết thúc trước mọi thao tác gửi thư, gọi agent hoặc cập nhật dữ liệu nghiệp vụ.

Chữ ký hợp lệ có ngăn được phát lại không?

Khi thiết kế điểm nhận cho một giao thức dùng HMAC, hãy tách ba câu hỏi:

Một yêu cầu được gửi lại có thể giữ nguyên dữ liệu và mã xác thực. Vì vậy, kết quả HMAC khớp không thay thế hai kiểm tra còn lại.

Nếu giao thức dùng timestamp để chống phát lại, giá trị thời gian cần được ràng buộc vào dữ liệu xác thực. Chính sách phía máy chủ nhận cũng cần xác định đơn vị thời gian, sai lệch đồng hồ được chấp nhận và cách tương thích với việc gửi lại. Chỉ có một header thời gian chưa đủ để thiết kế kiểm tra này.

Tương tự, đừng chọn một header làm khoá loại trùng chỉ vì tên có chữ “Delivery”. Thiết kế loại trùng phải dựa trên ý nghĩa, phạm vi duy nhất và quy tắc sử dụng mã giao nhận của giao thức đang triển khai.

Nếu bước xử lý sự kiện có gửi email qua API, xem cách chống gửi email trùng bằng Idempotency-Key cho bước gửi; đây là việc riêng với xác minh chữ ký webhook.

Những lỗi xác minh HMAC nào cần kiểm tra?

Với bộ xác minh HMAC, khi mã xác thực không khớp, hãy tìm bước làm sai dữ liệu hoặc chọn sai bí mật. Đừng chữa bằng cách bỏ qua xác minh.

Cần kiểm thử gì trước khi bật xử lý thật?

Bộ ca thử cho một giao thức dùng HMAC nên đi qua đúng đường nhận yêu cầu của ứng dụng, gồm cả proxy và middleware. Với mỗi ca bị từ chối, kiểm tra rằng không có tác dụng phụ nghiệp vụ, thay vì chỉ nhìn phản hồi HTTP.

Với kiểm tra độ mới và loại trùng, bổ sung ca thời gian cũ, thời gian ở tương lai và yêu cầu gửi lại theo cơ chế tương ứng. Ghi môi trường, ngày chạy, kết quả và tác dụng phụ quan sát được để có thể chạy lại sau khi thay middleware hoặc proxy.

Webhook đã xác minh có an toàn để chuyển cho AI agent?

Chữ ký xác thực yêu cầu webhook không biến nội dung email thành lệnh đáng tin. Email đến vẫn là dữ liệu không tin cậy, kể cả khi bộ xác minh chấp nhận sự kiện.

Agent không được làm theo chỉ dẫn trong thư để tiết lộ bí mật, thay đổi quyền hoặc gửi nội dung ra ngoài. Hãy cấp khoá ít quyền, tách quyền quản lý webhook khỏi quyền send, và yêu cầu xác nhận trước khi agent gửi thư. Xem thêm mẫu ứng dụng phê duyệt qua email.

Nếu webhook là đầu vào của hệ thống agent, hãy giữ ranh giới này xuyên suốt luồng dùng hộp thư có sẵn cho AI agent. Bạn cũng có thể tham khảo thông tin bảo mật Mailera khi rà quyền truy cập và cách quản lý bí mật.