Webhook có JSON đọc được chưa chứng minh nó đến từ đúng hệ thống gửi. Xác minh chữ ký webhook cần thực hiện theo quy tắc của provider, trên dữ liệu mà provider thực sự ký. Một middleware chuyển đổi body trước bước này có thể khiến request hợp lệ bị từ chối, hoặc khiến đội vận hành bỏ qua xác minh để “cho chạy được”.
Chữ ký được tính trên dữ liệu nào?
Stripe yêu cầu raw body nguyên bản cho bước kiểm chữ ký. Không parse JSON rồi serialize lại để thay thế: khoảng trắng, thứ tự hoặc cách biểu diễn ký tự có thể khác dù đối tượng nhìn giống nhau. Dùng thư viện và hướng dẫn chính thức của provider, đúng endpoint signing secret và môi trường. Secret dùng cho webhook không mặc định là API key gọi API.
Giữ nguyên body cho xác minh không có nghĩa lưu body đầy đủ vào log. Dữ liệu sự kiện có thể chứa thông tin riêng tư. Quy trình chẩn đoán nên lưu kết quả, định danh endpoint, kích thước hoặc hash phù hợp và mã tham chiếu được phép; phần nội dung cần thiết phải có quyền đọc, thời hạn lưu và cơ chế che dữ liệu riêng.
Phiếu bằng chứng tối thiểu
| Điểm kiểm | Cần ghi | Không ghi công khai |
|---|---|---|
| Endpoint | Môi trường, phiên bản cấu hình | Signing secret |
| Body | Cách đọc raw, độ dài, hash khi được phép | Toàn bộ payload riêng tư |
| Chữ ký | PASS/FAIL và lớp nguyên nhân | Thông tin xác thực có thể tái sử dụng |
| Xử lý | event_id đã xác minh, kết quả nghiệp vụ | Khẳng định hoàn tất chỉ từ HTTP 200 |
Ví dụ giả định: sửa middleware, không tắt kiểm tra
Một endpoint trả lỗi chữ ký sau khi thêm lớp đọc JSON dùng chung. Đội triển khai kiểm tra thứ tự middleware, so hash body tại điểm nhận với điểm xác minh trong môi trường được phép, và xác nhận secret thuộc đúng endpoint. Nếu nguyên nhân là body bị chuyển đổi, sửa đúng đường đọc body. Không giải quyết bằng cách bỏ xác minh cho mọi request. Đây là tình huống minh họa, không phải chẩn đoán production Onter.
Timestamp và event_id trả lời hai câu hỏi khác nhau
Timestamp trong cơ chế của Stripe giúp hạn chế phát lại request cũ trong cửa sổ kiểm tra. Nó không thay thế nhận diện sự kiện được gửi lại hợp lệ. Một lần giao mới có thể mang chữ ký và thời điểm mới nhưng vẫn đại diện cùng sự kiện. Sau xác minh, tầng nghiệp vụ vẫn phải phân biệt sự kiện mới, trùng hoặc đã áp dụng mà chưa lưu được biên nhận.
- Chữ ký sai: không chạy tác động nghiệp vụ; chẩn đoán provider, secret và raw body.
- Thời gian không hợp lệ: kiểm tra đồng hồ và chính sách provider, không tự bỏ giới hạn.
- Chữ ký hợp lệ, event_id đã xử lý: áp dụng chính sách trùng đã được chốt.
- Chữ ký hợp lệ, trạng thái đến muộn: kiểm tra phiên bản nghiệp vụ riêng.
Bước cuối khác với xác minh nguồn. Bài webhook đến sai thứ tự xử lý việc giữ đúng trạng thái sau khi sự kiện đã được tin cậy. Tách hai ranh giới giúp đội vận hành biết lỗi ở đầu vào hay ở logic cập nhật.
Chuẩn bị một lần bàn giao có thể truy vết
Với tích hợp webhook trong phần mềm, hãy đưa sơ đồ middleware và phiếu bằng chứng vào phạm vi nghiệm thu. Chỉ nhận hoàn tất khi có thể phân biệt request bị từ chối, sự kiện đã nhận và tác động đã áp dụng; không cần lộ secret để chứng minh điều đó.
Nguồn tham khảo và giới hạn
Stripe: Receive Stripe events in your webhook endpoint (đọc ngày 13/10/2026). Các biểu mẫu và tình huống trong bài là hướng dẫn biên tập hoặc ví dụ giả định; không phải kết quả kiểm thử, dữ liệu khách hàng hay cam kết năng lực đã triển khai. Cách áp dụng cần đối chiếu nền tảng và quyền thực tế.
