Replay webhook gửi lại một callback HTTP đã bắt trước đó tới handler cục bộ của bạn mà không cần yêu cầu nhà cung cấp upstream gửi lại sự kiện. Thay vì kích hoạt lại một khoản thanh toán Stripe, một push GitHub hay một tin nhắn Twilio, bạn replay đúng request đó — header, body và mọi thứ — từ lịch sử request của mình.
Vì sao replay webhook quan trọng
Gỡ lỗi webhook thường rơi vào một vòng lặp mệt mỏi: kích hoạt sự kiện, kiểm tra lần gửi, tìm bug, sửa code, kích hoạt lại. Kích hoạt lại sự kiện upstream thì chậm, ồn ào và đôi khi bất khả thi (sự kiện thanh toán một lần, tài nguyên đã xóa, hoặc API test bị giới hạn tốc độ).
Replay rút gọn vòng lặp đó. Bắt một lần, sửa handler, replay cùng một payload cho đến khi thành công — hoàn toàn không đụng tới nhà cung cấp bên ngoài.
Replay webhook hoạt động thế nào
- Một callback đến URL tunnel của bạn và được chuyển tiếp tới ứng dụng cục bộ.
- Công cụ tunnel bắt toàn bộ request: method, path, header và body.
- Bạn sửa code handler dựa trên những gì thấy trong request đã bắt.
- Bạn replay request đã bắt tới endpoint cục bộ chỉ bằng một thao tác.
- Lặp lại cho đến khi handler trả về phản hồi đúng.
Quy trình này cần một tunnel localhost có bắt request tích hợp sẵn — không chỉ chuyển tiếp lưu lượng.
Các tình huống dùng replay webhook
Phát triển handler
Xây và kiểm thử handler webhook theo cách lặp. Replay cùng một sự kiện Stripe checkout.session.completed mười lần trong khi tinh chỉnh logic parse.
Kiểm thử tính bất biến (idempotency)
Nhà cung cấp gửi sự kiện trùng lặp khi retry. Replay cùng một payload nhiều lần để xác nhận handler xử lý bản trùng một cách an toàn — không tính phí đôi hay tạo bản ghi trùng.
Gỡ lỗi xác minh chữ ký
Khi kiểm tra chữ ký thất bại, replay request gốc với header nguyên vẹn để khoanh vùng xem vấn đề nằm ở logic xác minh hay parse payload.
Kiểm thử hồi quy
Lưu các request đã bắt từ sự kiện test gần với production và replay chúng sau khi refactor để bắt các thay đổi gây lỗi trước khi deploy.
Replay webhook với PortPreview
- Khởi chạy ứng dụng và chạy
npx portpreview 3000. - Cấu hình nhà cung cấp gửi callback tới URL tunnel.
- Kích hoạt một sự kiện test và kiểm tra request đã bắt trong PortPreview.
- Sửa handler, rồi replay request đã bắt.
- Xác minh trạng thái và body phản hồi mà không cần kích hoạt lại nhà cung cấp.
PortPreview giữ nguyên header gốc nên việc xác minh chữ ký của nhà cung cấp vẫn có ý nghĩa khi replay.
Replay so với kích hoạt lại: khi nào dùng cái nào
- Replay: lỗi logic handler, parse payload, kiểm tra idempotency, gỡ lỗi chữ ký.
- Kích hoạt lại: kiểm thử việc tạo sự kiện phía nhà cung cấp, xác minh đăng ký webhook, hoặc tích hợp đầu-cuối với trạng thái thực của nhà cung cấp.
Về cấu hình cho từng nhà cung cấp, xem hướng dẫn về kiểm thử webhook Stripe cục bộ, kiểm thử webhook GitHub cục bộ và kiểm thử webhook Twilio cục bộ.
Thực hành tốt khi replay webhook
- Luôn xác minh chữ ký khi replay, không chỉ ở lần gửi đầu tiên.
- Kiểm thử việc gửi trùng bằng cách replay cùng một sự kiện nhiều lần.
- Giữ lịch sử request trong các nhánh feature để kiểm tra hồi quy.
- Dùng thông tin xác thực chế độ test để sự kiện replay không bao giờ ảnh hưởng dữ liệu production.
Tham gia danh sách chờ PortPreview để có khả năng bắt và replay webhook tích hợp ngay trong quy trình tunnel của bạn.