Để kiểm tra một webhook, bạn cung cấp cho nhà cung cấp một URL có thể truy cập, kích hoạt một sự kiện thực tế, sau đó xác nhận rằng trình xử lý của bạn chấp nhận tải trọng (payload) và phản ứng chính xác. Phần khó khăn là ứng dụng của bạn là bên nhận, không phải bên gọi, vì vậy bạn không thể chỉ nhấn "Gửi" và đọc phản hồi. Hướng dẫn này sẽ trình bày các công cụ bạn cần (dịch vụ kiểm tra, đường hầm cục bộ, trình kích hoạt từ nhà cung cấp) và một quy trình lặp lại để xác nhận trình xử lý của bạn từ đầu đến cuối.
Tại sao webhooks khó kiểm tra hơn API thông thường
Với một lệnh gọi API thông thường, bạn kiểm soát yêu cầu. Bạn chọn phương thức, thiết lập nội dung, gửi nó và đọc phản hồi. Webhooks đảo ngược điều đó. Nhà cung cấp gửi yêu cầu đến bạn, theo lịch trình riêng của họ, với một tải trọng mà họ định nghĩa. Sự đảo ngược vai trò này tạo ra bốn vấn đề khi kiểm tra.
Thứ nhất, theo mặc định, bạn không thể tự kích hoạt sự kiện. Một sự kiện payment_intent.succeeded chỉ kích hoạt khi Stripe quyết định nó đã thành công, vì vậy bạn cần công cụ của nhà cung cấp để buộc một sự kiện.
Thứ hai, việc gửi là bất đồng bộ. Sự kiện đến bất cứ khi nào hành động ngược dòng hoàn tất, vì vậy kiểm thử của bạn phải nắm bắt một yêu cầu đến thay vì chặn một giá trị trả về.
Thứ ba, cấu trúc tải trọng được định nghĩa bởi nhà cung cấp. Trình xử lý của bạn phải phân tích chính xác những gì GitHub, Stripe hoặc Slack gửi.
Thứ tư, hầu hết các nhà cung cấp đều ký các yêu cầu của họ. Điểm cuối của bạn phải xác minh tiêu đề chữ ký trước khi tin tưởng nội dung, và một kiểm thử bỏ qua bước này sẽ che giấu các lỗi thực sự. Để tìm hiểu sâu hơn, hãy xem hướng dẫn của chúng tôi về xác minh chữ ký webhook.
Nếu bạn vẫn đang cân nhắc liệu webhooks có phải là mô hình phù hợp cho tích hợp của mình hay không, webhooks so với polling và webhook so với WebSocket so sánh các đánh đổi.
Bộ công cụ kiểm tra webhook
Bạn sẽ cần bốn loại công cụ, thường là trong cùng một phiên: dịch vụ thu thập để xem các tải trọng thô, một đường hầm để kết nối với máy tính xách tay của bạn, các trình kích hoạt từ nhà cung cấp để gửi các sự kiện thực tế, và một công cụ xác nhận để kiểm tra trình xử lý của bạn.
1. Dịch vụ kiểm tra và thu thập
Trước khi bạn viết một dòng mã trình xử lý nào, hãy hướng nhà cung cấp đến một URL dùng một lần và xem nó thực sự gửi gì. Các dịch vụ này cung cấp cho bạn một điểm cuối công khai và hiển thị mọi yêu cầu theo thời gian thực.
webhook.site cung cấp cho bạn một URL ngẫu nhiên và địa chỉ email duy nhất ngay khi trang tải. Mọi thứ được gửi đến đó sẽ xuất hiện ngay lập tức: toàn bộ nội dung, tiêu đề và phương thức. Các URL miễn phí hết hạn sau 7 ngày và giới hạn ở 100 yêu cầu, với kích thước yêu cầu tối đa 10 MB. Các gói trả phí bổ sung các URL vĩnh viễn, yêu cầu không giới hạn và lịch sử được giữ lại của 10.000 yêu cầu gần nhất.
Beeceptor cung cấp một điểm cuối HTTPS miễn phí mà bạn có thể sử dụng làm bộ nhận webhook và kiểm tra các tải trọng đến theo thời gian thực. Nó cũng cung cấp các điểm cuối máy chủ giả lập, vì vậy bạn có thể thu thập và mô phỏng từ cùng một công cụ.
Pipedream RequestBin là một công cụ thu thập yêu cầu được sử dụng rộng rãi khác. Hãy kiểm tra tài liệu hiện tại của nó để biết chi tiết cấp độ, vì các dịch vụ thu thập thường thay đổi giới hạn miễn phí của họ.
Sử dụng các công cụ này để trả lời một câu hỏi: tải trọng thực tế trông như thế nào? Sao chép một mẫu để sử dụng sau này, khi bạn xây dựng các kiểm thử có thể lặp lại.
2. Phát triển cục bộ: phơi bày localhost bằng một đường hầm
Các nhà cung cấp không thể truy cập localhost:3000 trên máy của bạn. Một đường hầm tạo ra một URL HTTPS công khai chuyển tiếp lưu lượng truy cập đến cổng cục bộ của bạn, để bạn có thể chạy trình xử lý của mình trong trình chỉnh sửa và gỡ lỗi trực tiếp.
ngrok là lựa chọn phổ biến. Cài đặt nó, xác thực một lần, sau đó chuyển tiếp một cổng.
brew install ngrok # macOS
ngrok config add-authtoken $YOUR_TOKEN
ngrok http 3000 # chuyển tiếp một URL HTTPS công khai đến localhost:3000
Các tài khoản ngrok miễn phí sẽ nhận được một miền phát triển được chọn tự động. Các miền tùy chỉnh yêu cầu gói trả phí.
cloudflared chạy một đường hầm nhanh chóng chỉ với một lệnh nếu bạn thích Cloudflare.
cloudflared tunnel --url http://localhost:3000
Dán URL công khai mà đường hầm in ra vào cài đặt webhook của nhà cung cấp, và các sự kiện đến sẽ được chuyển đến máy chủ cục bộ của bạn. Để biết hướng dẫn chi tiết hơn về mô hình này, hãy xem cách kiểm tra API localhost với các dịch vụ webhook.
3. Kích hoạt sự kiện kiểm thử từ nhà cung cấp
Một URL thu thập chỉ hữu ích khi có thứ gì đó được gửi đến nó. Hầu hết các nhà cung cấp lớn đều cung cấp công cụ để kích hoạt các sự kiện kiểm thử theo yêu cầu, vì vậy bạn không phải tạo ra các khoản thanh toán hoặc đẩy dữ liệu thực tế.
Stripe CLI là ví dụ rõ ràng nhất. Lệnh stripe listen chuyển tiếp các sự kiện trực tiếp từ sandbox Stripe của bạn đến một đường dẫn cục bộ, và nó in ra một khóa bí mật ký webhook mà bạn đặt trong cấu hình ứng dụng của mình.
# Chuyển tiếp tất cả sự kiện đến trình xử lý cục bộ của bạn:
stripe listen --forward-to localhost:3000/webhooks
# Chỉ lọc các sự kiện cụ thể:
stripe listen --events payment_intent.succeeded,checkout.session.completed \
--forward-to localhost:3000/webhooks
Với trình lắng nghe đang chạy, stripe trigger sẽ kích hoạt một sự kiện kiểm thử. Lưu ý rằng việc kích hoạt tạo ra các đối tượng API được hỗ trợ đúng cách và có các tác dụng phụ: payment_intent.succeeded cũng phát ra payment_intent.created.
stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed
stripe trigger --help # liệt kê mọi sự kiện được hỗ trợ
GitHub lưu giữ một lịch sử phân phối ngắn mà bạn có thể phát lại. Truy cập kho lưu trữ của bạn, sau đó vào Cài đặt (Settings), sau đó Webhooks trong phần "Code and automation." Nhấp vào URL webhook, mở tab "Recent deliveries", nhấp vào GUID phân phối, và nhấp "Redeliver." Có hai hạn chế quan trọng: bạn chỉ có thể phát lại các lần phân phối từ 3 ngày qua, và bạn cần quyền truy cập quản trị vào kho lưu trữ. GitHub không tự động phát lại các lần phân phối thất bại, vì vậy việc phát lại là thủ công.
Các webhook đến của Slack là đơn giản nhất để kiểm tra. Bạn gửi một tin nhắn bằng cách POST JSON đến URL webhook. Tải trọng tối thiểu chỉ là một trường text.
curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
-H 'Content-type: application/json' \
-d '{"text":"Hello, world."}'
URL webhook của Slack là một bí mật. Slack thu hồi các URL bị lộ, vì vậy hãy giữ nó tránh xa mã phía máy khách (client-side code) và các kho lưu trữ công khai.
4. Xác nhận trình xử lý của bạn
Việc thu thập và kích hoạt chứng minh rằng hệ thống hoạt động. Chúng không chứng minh trình xử lý của bạn là chính xác. Công cụ cuối cùng gửi một tải trọng được tạo sẵn và kiểm tra phản hồi cùng với các tác dụng phụ. Ở mức cơ bản nhất, đó là một lệnh curl với một nội dung đại diện.
curl -X POST http://localhost:3000/webhooks \
-H 'Content-Type: application/json' \
-H 'Stripe-Signature: t=...,v1=...' \
-d '{"id":"evt_test","type":"payment_intent.succeeded","data":{"object":{"id":"pi_123","status":"succeeded"}}}'
Một lệnh curl đơn lẻ tốt cho một kiểm thử nhanh (smoke test). Nó trở nên thiếu sót khi bạn muốn các kiểm thử có thể lặp lại, được xác nhận chạy trong CI. Đó là lúc một công cụ API chuyên dụng khẳng định giá trị của mình.
Kiểm tra webhooks với Apidog
Apidog là một nền tảng API tất cả trong một để thiết kế, gỡ lỗi, kiểm tra, giả lập và tạo tài liệu API. Nó không có "hộp thư webhook" chuyên dụng, vì vậy phần này trung thực về những gì nó thực sự làm tốt: tạo tải trọng, lưu chúng, xác nhận phản hồi và đóng vai nhà cung cấp với một máy chủ giả lập.
Tạo và lưu một tải trọng mẫu dưới dạng yêu cầu có thể tái sử dụng
Lấy tải trọng bạn đã thu thập từ webhook.site (hoặc sao chép từ tài liệu của nhà cung cấp) và xây dựng nó thành một yêu cầu Apidog. Đặt phương thức là POST, dán nội dung JSON và thêm các tiêu đề mà nhà cung cấp gửi, bao gồm tiêu đề chữ ký mà trình xử lý của bạn kiểm tra.
Lưu yêu cầu đó vào điểm cuối của bạn. Giờ đây, bạn có một cách có thể lặp lại, có kiểm soát phiên bản để POST một tải trọng đã biết là tốt (hoặc cố ý bị lỗi) đến trình xử lý của bạn, thay vì gõ lại lệnh curl mỗi lần.
Xác nhận phản hồi bằng công cụ xây dựng xác nhận trực quan
Gửi tải trọng là một nửa của bài kiểm tra. Nửa còn lại là kiểm tra những gì trình xử lý của bạn trả về. Trong bước yêu cầu hoặc kịch bản, hãy mở Post Processors, nhấp vào “+ Add,” và chọn “Assertion.” Apidog thêm một quy tắc xác thực mà bạn cấu hình mà không cần mã.
Hướng xác nhận vào phần nội dung phản hồi và sử dụng $ cho gốc JSON. Ví dụ, nhắm mục tiêu $.data.status, đặt điều kiện là Equals (Bằng), và so sánh với succeeded (thành công). Chạy yêu cầu, và kết quả sẽ hiển thị trong tab Assertion. Các xác nhận trực quan so sánh các giá trị dưới dạng chuỗi. Khi bạn cần kiểm tra chính xác kiểu dữ liệu (một số thực, một giá trị boolean), hãy chuyển sang một tập lệnh tùy chỉnh sử dụng cú pháp pm.test tương thích với Postman.
Điều này biến "nó trả về 200" thành "nó trả về 200, trường trạng thái là succeeded, và ID đơn hàng khớp." Xây dựng nhiều xác nhận vào một kịch bản để bao gồm đường dẫn thành công, trường hợp thiếu trường, và từ chối chữ ký không hợp lệ.
Sử dụng máy chủ giả lập để đóng vai nhà cung cấp
Đôi khi bạn muốn kiểm tra theo hướng ngược lại: một dịch vụ trong hệ thống của bạn gọi đến một nhà cung cấp. Trong quá trình kiểm tra cục bộ, bạn có thể không muốn thực sự gọi đến nhà cung cấp. Máy chủ giả lập của Apidog cho phép bạn thay thế nó.
Apidog cung cấp ba loại giả lập. Local Mock (Giả lập cục bộ) chạy với ứng dụng khách trên máy tính để bàn và chỉ hoạt động khi ứng dụng khách đang mở. Cloud Mock (Giả lập đám mây) được lưu trữ trên các máy chủ của Apidog, chạy 24/7 và có thể bật hoặc tắt (mặc định là tắt). Runner Mock (Giả lập Runner) chạy trên cơ sở hạ tầng runner tự lưu trữ và được chia sẻ trong nhóm của bạn. Mỗi điểm cuối HTTP có một mô-đun Mock; sao chép URL giả lập từ tab API trong chế độ Thiết kế hoặc tab Mock trong chế độ Gỡ lỗi. Chỉ các đường dẫn bắt đầu bằng / mới được định tuyến đến môi trường giả lập. Hướng mã của bạn đến URL giả lập đó trong quá trình kiểm tra, và tích hợp của bạn sẽ nhận được các phản hồi dự đoán từ nhà cung cấp mà không cần các lệnh gọi API thực tế hoặc các tác dụng phụ.
Chạy kiểm thử webhook trong CI với Apidog CLI
Khi kịch bản của bạn vượt qua kiểm thử cục bộ, hãy chạy nó trên mỗi lần đẩy với Apidog CLI. Nó yêu cầu Node.js v16 trở lên.
npm install -g apidog-cli
node -v && apidog -v && which node && which npm && which apidog # xác minh cài đặt
Chạy một kịch bản đã lưu trực tuyến, truyền mã thông báo truy cập và ID từ tab "Command line" trong CI/CD của kịch bản.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -d 3497013 -r html,cli
Ở đây, -t là kịch bản kiểm thử, -e là môi trường (bắt buộc), -d là dữ liệu kiểm thử (đường dẫn tệp CSV hoặc JSON, hoặc ID bộ dữ liệu đã lưu trữ), và -r đặt các trình báo cáo, chấp nhận cli, html, json, và junit. Để biết hướng dẫn chi tiết về dòng lệnh, hãy xem hướng dẫn Apidog CLI.
Bạn muốn xây dựng và xác nhận các kiểm thử webhook của riêng mình một cách trực quan? Hãy dùng thử Apidog miễn phí, không yêu cầu thẻ tín dụng.
Quy trình kiểm tra webhook từng bước
Kết hợp các công cụ lại với nhau, đây là một chuỗi các bước có thể lặp lại.
- 1. Kiểm tra tải trọng thực tế. Hướng nhà cung cấp đến một URL của webhook.site và thu thập một sự kiện thực tế. Ghi chú cấu trúc nội dung, tiêu đề và định dạng chữ ký.
- 2. Kết nối đến mã của bạn. Khởi động trình xử lý của bạn cục bộ, mở một đường hầm với
ngrok http 3000hoặccloudflared, và đặt URL công khai vào cấu hình webhook của nhà cung cấp. - 3. Kích hoạt một sự kiện thực tế. Sử dụng
stripe trigger, nút Redeliver của GitHub, hoặc một POST của Slack để gửi một sự kiện chính hãng qua đường hầm. - 4. Xác minh việc xử lý chữ ký. Gửi cùng một tải trọng với chữ ký hợp lệ và sau đó với một chữ ký đã bị làm giả. Trình xử lý của bạn phải chấp nhận cái đầu tiên và từ chối cái thứ hai.
- 5. Xác nhận phản hồi và các tác dụng phụ. Lưu tải trọng dưới dạng yêu cầu Apidog, thêm các xác nhận vào nội dung và trạng thái phản hồi, và xác nhận rằng hàng trong cơ sở dữ liệu hoặc lệnh gọi xuôi dòng đã xảy ra.
- 6. Tự động hóa nó. Chuyển kịch bản vào Apidog CLI để nó chạy trong CI mỗi khi có thay đổi.
Nếu bạn đang thiết kế hệ thống webhook chứ không chỉ sử dụng một cái, cách thiết kế webhooks đáng tin cậy và các thực hành tốt nhất cho webhook thanh toán bao gồm thử lại, tính bất biến (idempotency) và bảo mật. Để có cái nhìn rộng hơn, hướng dẫn API webhooks và webhooks và kiến trúc hướng sự kiện giải thích vị trí của webhooks trong một hệ thống lớn hơn.
Các câu hỏi thường gặp
Làm thế nào để kiểm tra một webhook?
Cung cấp cho nhà cung cấp một URL có thể truy cập, kích hoạt một sự kiện thực tế hoặc kiểm thử, sau đó xác nhận rằng trình xử lý của bạn nhận được tải trọng, xác minh chữ ký, trả về trạng thái chính xác và thực hiện tác dụng phụ mong muốn. Đầu tiên, hãy thu thập một tải trọng thực tế, sau đó xây dựng một yêu cầu có thể lặp lại với các xác nhận để kiểm thử luôn chạy theo cùng một cách.
Làm thế nào để kiểm tra webhooks cục bộ?
Chạy trình xử lý của bạn trên một cổng cục bộ, sau đó phơi bày nó bằng một đường hầm để nhà cung cấp có thể truy cập máy của bạn. Sử dụng ngrok http 3000 hoặc cloudflared tunnel --url http://localhost:3000, dán URL HTTPS công khai vào cài đặt webhook của nhà cung cấp, và kích hoạt một sự kiện. Các yêu cầu đến sẽ được chuyển đến máy chủ cục bộ của bạn, nơi bạn có thể đặt các điểm dừng (breakpoints) và kiểm tra chúng trực tiếp.
Làm thế nào để kiểm tra webhook với Postman?
Postman có thể POST một tải trọng được tạo sẵn đến điểm cuối của bạn và xác nhận phản hồi, nhưng nó không thể tự nhận một webhook đến thực sự. Điều tương tự cũng áp dụng cho Apidog: bạn xây dựng một yêu cầu với tải trọng và tiêu đề của nhà cung cấp, thêm các xác nhận vào nội dung và trạng thái phản hồi, và lưu nó dưới dạng một kiểm thử có thể tái sử dụng. Để thu thập một sự kiện đến đích thực, hãy ghép công cụ này với một dịch vụ thu thập hoặc một đường hầm.
Làm thế nào để kiểm tra webhook của Stripe?
Sử dụng Stripe CLI. Chạy stripe listen --forward-to localhost:3000/webhooks để chuyển tiếp các sự kiện sandbox đến trình xử lý của bạn và nhận một khóa bí mật ký. Sau đó chạy stripe trigger payment_intent.succeeded (hoặc bất kỳ sự kiện nào từ stripe trigger --help) để kích hoạt một sự kiện kiểm thử thực tế. Việc kích hoạt tạo ra các đối tượng API được hỗ trợ và có thể lan truyền, vì vậy payment_intent.succeeded cũng phát ra payment_intent.created.
Làm thế nào để kiểm tra webhook của Slack?
POST JSON đến URL webhook đến. Tải trọng hợp lệ tối thiểu là {"text":"Hello, world."}, được gửi kèm tiêu đề Content-type: application/json. Một kiểm thử thành công sẽ đăng tin nhắn vào kênh đã cấu hình. Giữ URL bí mật, vì Slack thu hồi các URL webhook bị lộ.
Làm thế nào để kiểm tra một URL webhook?
Gửi một yêu cầu POST mẫu đến URL và xác nhận rằng nó trả về trạng thái thành công và hoạt động chính xác. Kiểm tra nhanh nhất là một lệnh curl duy nhất với một nội dung đại diện. Đối với một kiểm thử thực tế, trước tiên hãy thu thập một tải trọng thực tế, gửi nó với cả chữ ký hợp lệ và không hợp lệ, và xác nhận phản hồi và các tác dụng phụ thay vì chỉ kiểm tra mã 200.