Kiểm thử webhook: gửi thử payload, đọc phản hồi và hiểu rào chắn CORS
Công cụ gửi một yêu cầu HTTP thật tới địa chỉ webhook bạn nhập, kèm phương thức, tiêu đề và phần thân do bạn tự đặt, rồi hiển thị mã trạng thái, tiêu đề phản hồi, nội dung phản hồi và thời gian phản hồi. Yêu cầu được phát đi từ chính trình duyệt của bạn nên có những điểm cần biết trước khi dùng, đặc biệt là chính sách CORS.
Tính năng nổi bật
- Chọn một trong năm phương thức GET, POST, PUT, PATCH và DELETE
- Thêm bớt tiêu đề tùy ý theo cặp khóa và giá trị, mặc định có sẵn Content-Type application/json
- Soạn phần thân yêu cầu tự do trong ô văn bản, không ràng buộc định dạng
- Ba mẫu payload dựng sẵn mô phỏng sự kiện thanh toán Stripe, sự kiện push GitHub và tin nhắn Slack
- Hiển thị mã trạng thái kèm nhãn, tô đỏ khi mã từ 400 trở lên
- Liệt kê đầy đủ các tiêu đề phản hồi mà trình duyệt cho phép đọc
- Tự nhận diện phản hồi dạng JSON để trình bày thụt lề, còn lại giữ nguyên văn bản thô
- Đo và hiển thị thời gian từ lúc gửi tới lúc nhận xong phần thân, tính bằng mili giây
Vì sao cần gửi thử webhook thay vì chờ sự kiện thật
Khi dựng một điểm nhận webhook, bạn phải trả lời được bốn câu hỏi trước khi nối vào hệ thống thật: địa chỉ có truy cập được từ bên ngoài không, lớp xác thực có cho qua không, bộ phân tích payload có đọc đúng cấu trúc không, và mã trạng thái trả về có đúng như bên gửi mong đợi không. Chờ sự kiện thật để kiểm tra bốn thứ đó rất tốn công: muốn thử một sự kiện thanh toán thành công thì phải tạo giao dịch, muốn thử sự kiện push thì phải commit và đẩy mã lên. Mỗi vòng lặp mất vài phút, mà lúc gỡ lỗi bạn cần hàng chục vòng lặp. Gửi thẳng một payload do bạn soạn rút vòng lặp xuống còn vài giây, và quan trọng hơn là bạn kiểm soát được nội dung để thử cả những trường hợp hiếm như thiếu trường, sai kiểu dữ liệu, hay chuỗi rỗng mà dịch vụ thật gần như không bao giờ gửi.
Lợi ích khi sử dụng
- Thử lại một payload chỉ mất vài giây thay vì phải tạo giao dịch hay đẩy mã lên kho lưu trữ
- Chủ động dựng những payload méo mó để kiểm tra nhánh xử lý lỗi của điểm nhận
- Thấy ngay mã trạng thái và thời gian phản hồi, phát hiện sớm điểm nhận xử lý quá chậm
- Không phải cài phần mềm khách HTTP nào, mở trình duyệt là dùng được
- Ba mẫu payload dựng sẵn giúp hình dung nhanh cấu trúc dữ liệu của các dịch vụ phổ biến
Cách gửi thử một webhook
- 1Dán địa chỉ điểm nhận webhook vào ô địa chỉ, nhớ ghi đầy đủ giao thức https ở đầu.
- 2Chọn phương thức trong danh sách thả xuống, phần lớn webhook dùng POST nên đây cũng là giá trị mặc định.
- 3Mở thẻ Headers để thêm các tiêu đề mà điểm nhận yêu cầu, chẳng hạn tiêu đề xác thực hoặc tiêu đề chữ ký riêng của dịch vụ.
- 4Sang thẻ Body soạn payload, hoặc bấm một trong ba nút mẫu để nạp nhanh cấu trúc quen thuộc rồi sửa lại theo ý.
- 5Bấm Gửi Webhook, đọc mã trạng thái ở khối phản hồi bên phải, rồi đối chiếu nội dung phản hồi với nhật ký phía máy chủ của bạn.
Vì sao rất nhiều yêu cầu báo lỗi CORS và cách xử lý
Đây là giới hạn quan trọng nhất của công cụ này, cần nói rõ ngay. Yêu cầu được phát đi bằng hàm fetch của chính trình duyệt bạn đang mở, nên nó chịu toàn bộ ràng buộc chia sẻ tài nguyên khác nguồn. Trình duyệt chỉ cho mã JavaScript đọc phản hồi khi máy chủ đích trả về tiêu đề Access-Control-Allow-Origin cho phép nguồn hiện tại. Điểm nhận webhook thì gần như không bao giờ đặt tiêu đề đó, vì chúng được thiết kế để nhận yêu cầu từ máy chủ khác chứ không từ trình duyệt. Nặng hơn nữa, khi bạn thêm tiêu đề tùy chỉnh hoặc dùng phương thức PUT, PATCH, DELETE, trình duyệt sẽ gửi trước một yêu cầu OPTIONS để hỏi phép; nếu máy chủ không trả lời đúng thì yêu cầu chính không bao giờ được phát đi. Khi đó công cụ hiện thông báo không gửi được kèm gợi ý về CORS. Cách xử lý: bật CORS cho môi trường phát triển, hoặc thử từ một công cụ chạy phía máy chủ. Lưu ý một sắc thái đáng giá: yêu cầu vẫn có thể đã tới máy chủ và đã được xử lý, chỉ là trình duyệt chặn không cho bạn đọc phản hồi. Hãy soi nhật ký máy chủ trước khi kết luận là gửi hỏng.
Chữ ký webhook và vì sao gửi thử thường bị từ chối
Các dịch vụ nghiêm túc đều ký payload để bên nhận biết yêu cầu đúng là do họ gửi. Cơ chế phổ biến là mã xác thực thông điệp dựa trên hàm băm: bên gửi lấy toàn bộ phần thân thô, tính giá trị băm với một khóa bí mật hai bên cùng biết, rồi đặt kết quả vào một tiêu đề riêng. Bên nhận tính lại đúng như vậy và so sánh hai chuỗi. Vì bạn không có khóa bí mật khi ngồi soạn payload thủ công, điểm nhận đã bật kiểm tra chữ ký sẽ trả về mã 401 hoặc 403 với mọi yêu cầu bạn gửi từ đây, và đó là dấu hiệu tốt chứ không phải lỗi. Muốn kiểm thử phần logic nghiệp vụ, bạn có hai lựa chọn: tạm tắt kiểm tra chữ ký bằng cờ cấu hình chỉ bật ở môi trường phát triển, hoặc tự tính chữ ký cho payload rồi dán vào tiêu đề tương ứng. Một điểm dễ vấp khi tự tính: chữ ký phải tính trên chuỗi thô đúng từng ký tự, nên nếu tầng trung gian đọc rồi tạo lại JSON thì khoảng trắng đổi và chữ ký sẽ lệch.
Đọc mã trạng thái theo đúng ngữ cảnh webhook
Mã 200 và 204 đều là chấp nhận, chọn mã nào tùy quy ước của bạn; nhiều bên gửi coi mọi mã thuộc dải 2xx là thành công. Mã 401 và 403 nghĩa là qua được lớp mạng nhưng bị chặn ở xác thực, thường do thiếu tiêu đề hoặc chữ ký không khớp. Mã 404 thường là sai đường dẫn hoặc bộ định tuyến không đăng ký phương thức bạn chọn. Mã 405 nói rõ đường dẫn có tồn tại nhưng không nhận phương thức đó, gặp nhiều khi bạn để nhầm GET. Mã 415 nghĩa là máy chủ không chấp nhận kiểu nội dung bạn khai; kiểm tra lại tiêu đề Content-Type. Mã 422 là payload đúng cú pháp nhưng sai ràng buộc nghiệp vụ, rất hữu ích khi thử payload thiếu trường. Dải 5xx là mã của bạn ném lỗi. Điều đáng nhớ nhất khi thiết kế điểm nhận: hãy trả mã 2xx ngay khi nhận được và đẩy phần xử lý nặng sang hàng đợi, vì phần lớn dịch vụ đặt hạn chờ ngắn rồi gửi lại nếu quá hạn.
Ba mẫu payload dựng sẵn dùng để làm gì
Nút Stripe Event nạp một cấu trúc gồm trường type mang tên sự kiện và một object lồng trong data, đúng kiểu bao bọc mà cổng thanh toán này dùng. Điểm hay để tập là dữ liệu thật luôn nằm sâu hai tầng chứ không nằm ở gốc, và số tiền được biểu diễn bằng đơn vị nhỏ nhất chứ không phải số thập phân, nên bộ phân tích của bạn phải xử lý đúng cả hai chỗ đó. Nút GitHub Push nạp cấu trúc có trường ref dạng đường dẫn nhánh đầy đủ, kèm thông tin kho lưu trữ và người đẩy mã; đây là nơi để kiểm tra logic lọc nhánh, vì rất nhiều đoạn mã cắt chuỗi sai và nhận nhầm nhánh có tên chứa từ khóa. Nút Slack Message nạp cấu trúc phẳng chỉ gồm nội dung và kênh, dùng khi bạn muốn kiểm tra chiều gửi đi tới một địa chỉ webhook đến. Cả ba đều là cấu trúc rút gọn để tập, không phải bản sao đầy đủ của payload thật, nên khi nối vào hệ thống thật hãy đọc lại tài liệu của dịch vụ.
Cẩn trọng khi dán khóa bí mật và địa chỉ nội bộ
Công cụ không lưu và không gửi dữ liệu của bạn về máy chủ nào của chúng tôi, nhưng có hai điều cần hiểu đúng. Thứ nhất, mọi tiêu đề bạn nhập đều được gửi tới đúng địa chỉ bạn gõ vào; nếu gõ nhầm tên miền thì khóa xác thực đã rời khỏi tầm kiểm soát của bạn. Vì vậy nên dùng khóa của môi trường thử nghiệm, đừng dùng khóa của môi trường vận hành, và sau khi thử xong với khóa nhạy cảm thì nên thu hồi và cấp lại. Thứ hai, vì yêu cầu phát đi từ máy của bạn nên nó đi qua đúng mạng bạn đang nối. Địa chỉ nội bộ trong mạng công ty có thể gọi được từ máy bạn nhưng dịch vụ bên ngoài lại không gọi tới được, và ngược lại; đừng vội kết luận điểm nhận đã sẵn sàng chỉ vì công cụ gọi thành công. Với địa chỉ chạy trên máy cá nhân, dịch vụ bên ngoài không thấy được, bạn cần một đường hầm công khai trỏ vào máy trước khi kiểm thử nối đầu cuối.
Câu hỏi thường gặp (FAQ)
Vì sao tôi luôn nhận lỗi không gửi được kèm chữ CORS?
Vì yêu cầu phát đi từ trình duyệt nên phải được máy chủ đích cho phép qua tiêu đề Access-Control-Allow-Origin. Điểm nhận webhook hầu như không đặt tiêu đề này vì chúng dành cho giao tiếp giữa máy chủ với máy chủ. Bạn nên soi nhật ký phía máy chủ, vì yêu cầu có thể đã tới nơi và được xử lý dù trình duyệt không cho đọc phản hồi.
Yêu cầu bị chặn nghĩa là chưa hề gửi đi phải không?
Không hẳn. Nếu chỉ là phản hồi bị chặn đọc thì yêu cầu đã tới máy chủ và có thể đã tạo dữ liệu thật. Nhưng nếu bị chặn ở bước hỏi phép bằng phương thức OPTIONS, xảy ra khi bạn thêm tiêu đề tùy chỉnh hoặc dùng PUT, PATCH, DELETE, thì yêu cầu chính chưa từng được phát đi. Chỉ nhật ký máy chủ mới phân biệt được hai trường hợp.
Có kiểm thử được điểm nhận chạy trên máy cá nhân không?
Được nếu địa chỉ đó truy cập được từ chính máy bạn, vì yêu cầu phát đi từ trình duyệt trên máy bạn chứ không từ máy chủ của chúng tôi. Tuy nhiên bạn có thể vướng lỗi nội dung hỗn hợp khi trang chạy trên https mà điểm nhận chạy trên http. Để kiểm thử nối đầu cuối với dịch vụ thật, bạn vẫn cần một đường hầm công khai.
Điểm nhận trả về mã 401 với mọi payload tôi gửi, sai ở đâu?
Nhiều khả năng điểm nhận đang kiểm tra chữ ký webhook mà payload bạn soạn tay không có chữ ký hợp lệ. Đây là hành vi đúng của một điểm nhận an toàn. Hãy tạm tắt kiểm tra chữ ký ở môi trường phát triển bằng cờ cấu hình, hoặc tự tính giá trị băm cho payload rồi đặt vào tiêu đề mà dịch vụ quy định.
Vì sao khối tiêu đề phản hồi hiện quá ít dòng so với thực tế?
Với yêu cầu khác nguồn, trình duyệt chỉ cho mã JavaScript đọc một nhóm tiêu đề cơ bản. Muốn thấy thêm, máy chủ phải liệt kê tên tiêu đề trong Access-Control-Expose-Headers. Đây là hạn chế của môi trường trình duyệt chứ không phải công cụ lọc bớt, nên tiêu đề giới hạn tần suất hay tiêu đề truy vết thường không hiện ra.
Con số mili giây hiển thị đo chính xác cái gì?
Đó là khoảng thời gian từ ngay trước khi phát yêu cầu tới khi đọc xong toàn bộ phần thân phản hồi, đo bằng đồng hồ của trình duyệt. Nó bao gồm cả độ trễ mạng từ vị trí bạn ngồi và thời gian tải nội dung, nên không phải thời gian xử lý thuần của máy chủ. Dùng để so sánh tương đối thì tốt, dùng làm số liệu hiệu năng chính thức thì không nên.
Chọn GET thì phần thân tôi soạn có được gửi không?
Không. Khi phương thức là GET, công cụ bỏ qua phần thân vì đặc tả HTTP không định nghĩa ngữ nghĩa cho thân của yêu cầu GET và trình duyệt cũng không cho gửi. Nếu cần truyền dữ liệu bằng GET, hãy đưa chúng vào chuỗi truy vấn ngay trên địa chỉ.
Điểm nhận webhook nên trả về mã trạng thái nào?
Trả 200 kèm phần thân ngắn hoặc 204 không phần thân đều được, miễn nằm trong dải 2xx. Điều quan trọng hơn là trả về nhanh: hãy ghi nhận sự kiện rồi đẩy phần xử lý nặng sang hàng đợi nền. Nếu bạn xử lý đồng bộ rồi mới trả lời, quá hạn chờ là bên gửi sẽ gửi lại và bạn có nguy cơ xử lý trùng.
Làm sao tránh xử lý trùng khi webhook được gửi lại?
Hầu hết dịch vụ đảm bảo giao ít nhất một lần chứ không phải đúng một lần, nên trùng lặp là chuyện bình thường. Cách xử lý là lấy định danh sự kiện trong payload làm khóa duy nhất, ghi vào bảng đã xử lý trước khi chạy nghiệp vụ, và bỏ qua nếu khóa đã tồn tại. Chỉ dựa vào dấu thời gian là không đủ.
Dán khóa xác thực thật vào ô tiêu đề có an toàn không?
Khóa không được gửi về máy chủ của chúng tôi, nhưng nó được gửi tới đúng địa chỉ bạn gõ vào, nên gõ nhầm tên miền là mất khóa. Hãy dùng khóa của môi trường thử nghiệm, và nếu buộc phải dùng khóa thật thì thu hồi rồi cấp lại sau khi kiểm thử xong. Đóng thẻ trình duyệt là toàn bộ dữ liệu nhập biến mất vì không có bước lưu.
Công cụ có lưu lịch sử các yêu cầu đã gửi không?
Không. Mỗi lần bấm gửi, kết quả cũ bị thay bằng kết quả mới và không có danh sách lịch sử, cũng không có chức năng xuất câu lệnh dòng lệnh tương đương. Nếu cần giữ lại một phản hồi để đối chiếu, hãy bấm nút sao chép ở góc khối phản hồi rồi dán ra nơi khác trước khi gửi yêu cầu tiếp theo.
Phần thân bắt buộc phải là JSON hợp lệ không?
Không. Ô soạn thảo nhận mọi chuỗi văn bản và gửi nguyên trạng, nên bạn có thể gửi XML, dữ liệu dạng biểu mẫu hay chuỗi cố tình sai cú pháp để thử nhánh xử lý lỗi. Chỉ cần nhớ sửa tiêu đề Content-Type cho khớp, vì nhiều khung ứng dụng chọn bộ phân tích dựa trên tiêu đề này chứ không đoán từ nội dung.
Từ khóa liên quan
- webhook tester
- test webhook online
- kiểm thử webhook
- gửi thử http request
- công cụ test api online
- debug webhook endpoint
- webhook trả về 401
- lỗi cors khi gọi api
- webhook signature là gì
- test webhook stripe
- test webhook github
- gửi post request online
- http status code webhook
- webhook retry và idempotency
- mô phỏng payload webhook
- kiểm tra endpoint nhận webhook
- công cụ thay postman online
- test webhook localhost
- webhook testing tool
- gửi request có custom header
