El replay de webhooks reenvía un callback HTTP capturado previamente a tu handler local sin pedirle al proveedor upstream que vuelva a entregar el evento. En lugar de volver a disparar un cargo de Stripe, un push de GitHub o un mensaje de Twilio, reproduces la petición exacta —cabeceras, cuerpo y todo— desde tu historial de peticiones.
Por qué importa el replay de webhooks
La depuración de webhooks suele seguir un bucle tedioso: disparar un evento, inspeccionar la entrega, encontrar un bug, arreglar el código, disparar de nuevo. Volver a disparar eventos upstream es lento, ruidoso y a veces imposible (eventos de pago de una sola vez, recursos eliminados o APIs de prueba con límite de tasa).
El replay reduce ese bucle. Captura una vez, arregla tu handler y reproduce el mismo payload hasta que pase, todo sin tocar al proveedor externo.
Cómo funciona el replay de webhooks
- Un callback llega a tu URL de túnel y se reenvía a tu app local.
- La herramienta de túnel captura la petición completa: método, ruta, cabeceras y cuerpo.
- Arreglas el código de tu handler según lo que ves en la petición capturada.
- Reproduces la petición capturada hacia tu endpoint local con una sola acción.
- Repites hasta que el handler devuelva la respuesta correcta.
Este flujo requiere un túnel a localhost con captura de peticiones integrada, no solo reenvío de tráfico.
Casos de uso del replay de webhooks
Desarrollo de handlers
Construye y prueba handlers de webhooks de forma iterativa. Reproduce el mismo evento checkout.session.completed de Stripe diez veces mientras afinas la lógica de parseo.
Pruebas de idempotencia
Los proveedores entregan eventos duplicados durante los reintentos. Reproduce el mismo payload varias veces para confirmar que tu handler procesa duplicados de forma segura, sin cobros dobles ni registros repetidos.
Depuración de verificación de firma
Cuando fallan las comprobaciones de firma, reproduce la petición original con cabeceras intactas para aislar si el problema está en la lógica de verificación o en el parseo del payload.
Pruebas de regresión
Guarda peticiones capturadas de eventos de prueba similares a producción y reprodúcelas tras los refactors para detectar cambios que rompan antes del deploy.
Replay de webhooks con PortPreview
- Inicia tu app y ejecuta
npx portpreview 3000. - Configura tu proveedor para enviar callbacks a la URL del túnel.
- Dispara un evento de prueba e inspecciona la petición capturada en PortPreview.
- Arregla tu handler y luego reproduce la petición capturada.
- Verifica el estado y el cuerpo de la respuesta sin volver a disparar el proveedor.
PortPreview preserva las cabeceras originales para que la verificación de firma del proveedor siga siendo válida durante el replay.
Replay vs. volver a disparar: cuándo usar cada uno
- Replay: bugs de lógica del handler, parseo de payload, comprobaciones de idempotencia, depuración de firmas.
- Volver a disparar: probar la generación de eventos del lado del proveedor, verificar el registro del webhook o la integración de extremo a extremo con el estado real del proveedor.
Para la configuración por proveedor, consulta las guías sobre probar webhooks de Stripe en local, probar webhooks de GitHub en local y probar webhooks de Twilio en local.
Buenas prácticas para el replay de webhooks
- Valida siempre las firmas durante el replay, no solo en la primera entrega.
- Prueba la entrega duplicada reproduciendo el mismo evento varias veces.
- Conserva el historial de peticiones durante las ramas de feature para comprobaciones de regresión.
- Usa credenciales en modo de prueba para que los eventos reproducidos nunca afecten los datos de producción.
Únete a la lista de espera de PortPreview para tener captura y replay de webhooks integrados en tu flujo de túnel.