Kiểm thử webhook Stripe trên máy cục bộ cho phép bạn xác thực các handler xử lý sự kiện thanh toán ngay trên máy mình trước khi đưa lên production. Bạn chạy ứng dụng cục bộ, mở nó qua một URL HTTPS công khai và nhận các sự kiện test-mode thật của Stripe với chức năng xác minh chữ ký được giữ nguyên vẹn.
Vì sao webhook Stripe cần URL công khai
Stripe gửi sự kiện webhook qua internet công cộng đến một URL endpoint đã cấu hình. Các địa chỉ như 127.0.0.1:3000 không thể truy cập từ máy chủ của Stripe, nên phát triển cục bộ cần một cầu nối. Một tunnel localhost ánh xạ một URL HTTPS công khai tới tiến trình cục bộ của bạn mà không cần thay đổi router hay tường lửa.
Bạn cần gì trước khi kiểm thử
- Một tài khoản Stripe ở chế độ test.
- Một ứng dụng cục bộ có route webhook (ví dụ
/api/webhooks/stripe). - Webhook signing secret của Stripe được cấu hình trong biến môi trường.
- Một công cụ tunnel giữ nguyên header của request để xác minh chữ ký.
Từng bước: kiểm thử webhook Stripe cục bộ với PortPreview
- Khởi chạy ứng dụng cục bộ trên cổng mục tiêu.
- Chạy
npx portpreview 3000để tạo URL HTTPS công khai. - Trong Stripe Dashboard, vào Developers → Webhooks và thêm URL tunnel cùng đường dẫn webhook của bạn.
- Chọn các sự kiện bạn muốn kiểm thử (ví dụ
checkout.session.completed,invoice.paid). - Kích hoạt sự kiện test từ Dashboard hoặc CLI của Stripe và kiểm tra từng lần gửi.
- Xác nhận handler trả về phản hồi 2xx và xác minh chữ ký thành công.
PortPreview ghi lại header, body và trạng thái phản hồi, giúp bạn gỡ lỗi các lần gửi thất bại mà không phải đoán mò chỉ từ log máy chủ.
Xác minh chữ ký webhook Stripe cục bộ
Đừng bao giờ tắt xác minh chữ ký khi phát triển. Stripe ký mỗi payload bằng webhook secret của bạn, và handler nên xác thực header Stripe-Signature giống hệt như trên production. Các công cụ tunnel giữ nguyên header gốc cho phép bạn kiểm thử đúng đường đi của code.
Các lỗi chữ ký thường gặp khi kiểm thử cục bộ:
- Dùng sai webhook secret (secret của Dashboard so với secret của CLI).
- Đọc body JSON đã được parse trước khi xác minh thay vì body thô của request.
- Lệch đồng hồ vượt quá cửa sổ dung sai của Stripe.
Những sự kiện đáng kiểm thử cục bộ
Checkout và subscription
Kiểm thử checkout.session.completed, customer.subscription.created và invoice.payment_failed để xác nhận việc cấp quyền, trao quyền truy cập và logic nhắc thanh toán.
Luồng Connect và marketplace
Nếu bạn dùng Stripe Connect, hãy xác thực các sự kiện cập nhật tài khoản và thông báo chuyển tiền với tài khoản kết nối test trước khi go-live.
Tính bất biến (idempotency) và retry
Stripe gửi lại các lần gửi thất bại. Dùng replay webhook để xác nhận handler xử lý sự kiện trùng lặp một cách an toàn.
Stripe CLI so với tunnel localhost
Stripe CLI có thể chuyển tiếp sự kiện bằng stripe listen --forward-to, phù hợp cho việc kiểm tra nhanh. Tunnel localhost cho bạn một URL công khai ổn định để dán vào Dashboard, chia sẻ với đồng đội và dùng cho nhiều nhà cung cấp — không chỉ Stripe. Nhiều nhóm dùng cả hai: CLI để lặp nhanh, tunnel cho kiểm thử tích hợp phản ánh cấu hình production.
Khi nào chuyển từ cục bộ sang staging
Kiểm thử cục bộ bao quát logic handler, parse payload và xác minh chữ ký. Hãy chuyển sang staging cho các kiểm tra đặc thù môi trường như secret được quản lý, migration cơ sở dữ liệu và pipeline release đầu-cuối. Với công việc tính năng thanh toán hằng ngày, kiểm thử webhook Stripe cục bộ rút ngắn vòng lặp từ vài phút xuống vài giây.
Đọc hướng dẫn đầy đủ về gỡ lỗi webhook cục bộ, hoặc tham gia danh sách chờ PortPreview cho quy trình tunnel ưu tiên webhook.