Para probar un webhook, se le proporciona al proveedor una URL accesible, se activa un evento real y luego se confirma que su manejador acepta la carga útil (payload) y reacciona correctamente. La parte difícil es que su aplicación es el receptor, no quien realiza la llamada, por lo que no puede simplemente hacer clic en "Enviar" y leer la respuesta. Esta guía le muestra las herramientas que necesita (servicios de inspección, túneles locales, activadores de proveedor) y un proceso repetible para verificar su manejador de extremo a extremo.
Por qué los webhooks son más difíciles de probar que las APIs normales
Con una llamada a API normal, usted controla la solicitud. Elige el método, establece el cuerpo, lo envía y lee la respuesta. Los webhooks invierten esto. El proveedor le envía la solicitud, según su propio cronograma, con una carga útil que define. Esa inversión de roles crea cuatro problemas de prueba.
Primero, por defecto no puede activar el evento usted mismo. Un evento de payment_intent.succeeded solo se dispara cuando Stripe decide que lo hizo, por lo que necesita herramientas del proveedor para forzar uno.
Segundo, la entrega es asíncrona. El evento llega cuando la acción anterior se completa, por lo que su prueba debe capturar una solicitud entrante en lugar de esperar un valor de retorno.
Tercero, la forma de la carga útil es definida por el proveedor. Su manejador tiene que analizar exactamente lo que envían GitHub, Stripe o Slack.
Cuarto, la mayoría de los proveedores firman sus solicitudes. Su punto final debe verificar un encabezado de firma antes de confiar en el cuerpo, y una prueba que omita esto oculta errores reales. Para una mirada más profunda, consulte nuestra guía sobre verificación de firma de webhook.
Si aún está decidiendo si los webhooks son el patrón correcto para su integración, webhooks vs polling y webhook vs WebSocket comparan las ventajas y desventajas.
El kit de herramientas para probar webhooks
Utilizará cuatro tipos de herramientas, a menudo en la misma sesión: un servicio de captura para ver cargas útiles sin procesar, un túnel para llegar a su ordenador portátil, activadores de proveedor para disparar eventos reales y una herramienta de aserción para verificar su manejador.
1. Servicios de inspección y captura
Antes de escribir una sola línea de código para su manejador, apunte el proveedor a una URL desechable y observe lo que realmente envía. Estos servicios le proporcionan un punto final público y muestran cada solicitud en tiempo real.
webhook.site le proporciona una URL y dirección de correo electrónico aleatorias únicas en el momento en que se carga la página. Todo lo que se le envía aparece instantáneamente: cuerpo completo, encabezados y método. Las URL gratuitas caducan después de 7 días y tienen un límite de 100 solicitudes, con un tamaño máximo de solicitud de 10 MB. Los planes de pago añaden URL permanentes, solicitudes ilimitadas y un historial conservado de las últimas 10.000 solicitudes.
Beeceptor ofrece un punto final HTTPS gratuito que puede usar como receptor de webhook e inspeccionar las cargas útiles entrantes en tiempo real. También proporciona puntos finales de servidores simulados (mock-server), para que pueda capturar y simular desde la misma herramienta.
Pipedream RequestBin es otra herramienta de captura de solicitudes ampliamente utilizada. Consulte su documentación actual para conocer los detalles de los niveles, ya que los servicios de captura cambian sus límites gratuitos con frecuencia.
Utilice estas herramientas para responder a una pregunta: ¿cómo se ve la carga útil real? Copie un ejemplo para más tarde, cuando cree pruebas repetibles.
2. Desarrollo local: exponer localhost con un túnel
Los proveedores no pueden acceder a localhost:3000 en su máquina. Un túnel crea una URL HTTPS pública que reenvía el tráfico a su puerto local, para que pueda ejecutar su manejador en su editor y depurarlo en vivo.
ngrok es la opción común. Instálelo, autentíquese una vez y luego reenvíe un puerto.
brew install ngrok # macOS
ngrok config add-authtoken $YOUR_TOKEN
ngrok http 3000 # reenvía una URL HTTPS pública a localhost:3000
Las cuentas gratuitas de ngrok obtienen un dominio de desarrollo elegido automáticamente. Los dominios personalizados requieren un plan de pago.
cloudflared ejecuta un túnel rápido con un solo comando si prefiere Cloudflare.
cloudflared tunnel --url http://localhost:3000
Pegue la URL pública que el túnel imprime en la configuración del webhook del proveedor, y los eventos entrantes aterrizarán en su servidor local. Para una explicación más completa de este patrón, consulte cómo probar APIs de localhost con servicios de webhook.
3. Activación de eventos de prueba desde el proveedor
Una URL de captura solo ayuda una vez que se le envía algo. La mayoría de los principales proveedores ofrecen herramientas para activar eventos de prueba bajo demanda, para que no tenga que generar pagos o notificaciones reales.
Stripe CLI es el ejemplo más claro. El comando stripe listen reenvía eventos en vivo desde su sandbox de Stripe a una ruta local, e imprime un secreto de firma de webhook que usted coloca en la configuración de su aplicación.
# Reenviar todos los eventos a su manejador local:
stripe listen --forward-to localhost:3000/webhooks
# Filtrar solo eventos específicos:
stripe listen --events payment_intent.succeeded,checkout.session.completed \
--forward-to localhost:3000/webhooks
Con el listener en ejecución, stripe trigger dispara un evento de prueba. Tenga en cuenta que la activación crea objetos de API respaldados correctamente y tiene efectos secundarios: payment_intent.succeeded también emite payment_intent.created.
stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed
stripe trigger --help # listar todos los eventos soportados
GitHub mantiene un breve historial de entregas que puede reproducir. Vaya a su repositorio, luego a Configuración, y luego a Webhooks debajo de "Código y automatización". Haga clic en la URL del webhook, abra la pestaña "Entregas recientes", haga clic en un GUID de entrega y haga clic en "Volver a entregar". Importan dos restricciones: solo puede volver a entregar entregas de los últimos 3 días, y necesita acceso de administrador al repositorio. GitHub no vuelve a entregar automáticamente las entregas fallidas, por lo que la reproducción es manual.
Los webhooks entrantes de Slack son los más sencillos de probar. Se envía un mensaje haciendo POST de JSON a la URL del webhook. La carga útil mínima es solo un campo text.
curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
-H 'Content-type: application/json' \
-d '{"text":"Hello, world."}'
La URL del webhook de Slack es un secreto. Slack revoca las URL que se filtran, así que manténgala fuera del código del lado del cliente y de los repositorios públicos.
4. Afirmando su manejador
Capturar y activar demuestran que la infraestructura funciona. No prueban que su manejador sea correcto. La herramienta final envía una carga útil elaborada y verifica la respuesta más los efectos secundarios. En su forma más básica, es un comando curl con un cuerpo representativo.
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"}}}'
Un solo curl está bien para una prueba de humo. Se queda corto cuando se desean pruebas repetibles y verificadas que se ejecuten en CI. Ahí es donde una herramienta de API dedicada se gana su lugar.
Probando webhooks con Apidog
Apidog es una plataforma API todo en uno para diseñar, depurar, probar, simular y documentar APIs. No tiene una "bandeja de entrada de webhook" dedicada, por lo que esta sección es honesta sobre lo que realmente hace bien: elaborar cargas útiles, guardarlas, afirmar respuestas y simular ser un proveedor con un servidor mock.
Crear y guardar una carga útil de ejemplo como una solicitud reutilizable
Tome la carga útil que capturó de webhook.site (o copió de la documentación de un proveedor) y constrúyala en una solicitud de Apidog. Establezca el método en POST, pegue el cuerpo JSON y añada los encabezados que el proveedor envía, incluido el encabezado de firma que su manejador verifica.
Guarde esa solicitud contra su punto final. Ahora tiene una forma repetible y con control de versiones para enviar una carga útil conocida y válida (o deliberadamente malformada) a su manejador, en lugar de volver a escribir un comando curl cada vez.
Verificar la respuesta con el constructor visual de aserciones
Enviar la carga útil es la mitad de la prueba. La otra mitad es verificar lo que devuelve su manejador. En el paso de solicitud o escenario, abra Post Processors, haga clic en "+ Add" y elija "Assertion". Apidog añade una regla de validación que configura sin código.
Apunte la aserción al cuerpo de la respuesta y use $ para la raíz JSON. Por ejemplo, apunte a $.data.status, establezca la condición en "Equals" (Igual a) y compare con succeeded (éxito). Ejecute la solicitud y el resultado se mostrará en la pestaña "Assertion". Las aserciones visuales comparan valores como cadenas. Cuando necesite comprobaciones precisas de tipo (un número real, un booleano), cambie a un script personalizado utilizando la sintaxis pm.test compatible con Postman.
Esto convierte "devolvió un 200" en "devolvió un 200, el campo de estado es exitoso y el ID del pedido coincide". Construya varias aserciones en un escenario para cubrir la ruta de éxito, un caso de campo faltante y un rechazo por firma incorrecta.
Usar un servidor simulado (mock server) para reemplazar al proveedor
A veces, querrá probar en la otra dirección: un servicio en su pila que llama a un proveedor. Durante las pruebas locales, es posible que no desee acceder al proveedor real en absoluto. El servidor simulado de Apidog le permite reemplazarlo.
Apidog ofrece tres tipos de simulaciones (mocks). Local Mock se ejecuta con el cliente de escritorio y funciona solo mientras el cliente está abierto. Cloud Mock está alojado en los servidores de Apidog, funciona 24/7 y se activa o desactiva (está desactivado por defecto). Runner Mock se ejecuta en infraestructura de runner autoalojada y se comparte entre su equipo. Cada punto final HTTP tiene un módulo Mock; copie la URL del mock desde la pestaña API en modo Diseño o la pestaña Mock en modo Depuración. Solo las rutas que comienzan con / se dirigen al entorno mock. Apunte su código a esa URL mock durante las pruebas, y su integración obtendrá respuestas de proveedor predecibles sin llamadas a API reales ni efectos secundarios.
Ejecutar pruebas de webhook en CI con Apidog CLI
Una vez que su escenario pase localmente, ejecútelo en cada push con Apidog CLI. Requiere Node.js v16 o posterior.
npm install -g apidog-cli
node -v && apidog -v && which node && which npm && which apidog # verificar instalación
Ejecute un escenario guardado en línea, pasando el token de acceso y los IDs de la pestaña "Command line" (Línea de comandos) de CI/CD del escenario.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -d 3497013 -r html,cli
Aquí -t es el escenario de prueba, -e es el entorno (obligatorio), -d son los datos de prueba (una ruta de archivo CSV o JSON, o un ID de conjunto de datos almacenado), y -r establece los reportes, que aceptan cli, html, json y junit. Para una explicación completa de la línea de comandos, consulte el tutorial de Apidog CLI.
¿Quiere construir y verificar sus propias pruebas de webhook visualmente? Pruebe Apidog gratis, no se requiere tarjeta de crédito.
Un flujo de trabajo paso a paso para probar webhooks
Reuniendo las herramientas, aquí tiene una secuencia repetible.
- Inspeccione la carga útil real. Apunte el proveedor a una URL de webhook.site y capture un evento real. Anote la forma del cuerpo, los encabezados y el formato de la firma.
- Alcance su código. Inicie su manejador localmente, abra un túnel con
ngrok http 3000ocloudflared, e inserte la URL pública en la configuración del webhook del proveedor. - Active un evento real. Utilice
stripe trigger, el botón "Redeliver" de GitHub o un POST de Slack para enviar un evento genuino a través del túnel. - Verifique el manejo de firmas. Envíe la misma carga útil con una firma válida y luego con una alterada. Su manejador debe aceptar la primera y rechazar la segunda.
- Afirme la respuesta y los efectos secundarios. Guarde la carga útil como una solicitud de Apidog, añada aserciones sobre el cuerpo y el estado de la respuesta, y confirme que la fila de la base de datos o la llamada posterior se realizó.
- Automatícelo. Mueva el escenario al Apidog CLI para que se ejecute en CI con cada cambio.
Si está diseñando el sistema de webhook en sí mismo en lugar de simplemente consumir uno, cómo diseñar webhooks confiables y mejores prácticas para webhooks de pago cubren reintentos, idempotencia y seguridad. Para una visión más amplia, la guía de la API de webhooks y webhooks y arquitectura basada en eventos explican dónde encajan los webhooks en un sistema más grande.
Preguntas Frecuentes
¿Cómo se prueba un webhook?
Proporcione al proveedor una URL accesible, active un evento real o de prueba, luego confirme que su manejador recibe la carga útil, verifica la firma, devuelve el estado correcto y realiza el efecto secundario esperado. Capture primero una carga útil real, luego cree una solicitud repetible con aserciones para que la prueba se ejecute de la misma manera cada vez.
¿Cómo se prueban los webhooks localmente?
Ejecute su manejador en un puerto local, luego expóngalo con un túnel para que el proveedor pueda acceder a su máquina. Utilice ngrok http 3000 o cloudflared tunnel --url http://localhost:3000, pegue la URL HTTPS pública en la configuración del webhook del proveedor y active un evento. Las solicitudes entrantes llegarán a su servidor local, donde podrá establecer puntos de interrupción e inspeccionarlas en vivo.
¿Cómo se prueba un webhook con Postman?
Postman puede enviar una carga útil elaborada a su punto final y verificar la respuesta, pero no puede recibir un webhook entrante real por sí mismo. Lo mismo se aplica a Apidog: usted construye una solicitud con la carga útil y los encabezados del proveedor, añade aserciones sobre el cuerpo y el estado de la respuesta, y la guarda como una prueba reutilizable. Para capturar un evento entrante genuino, combine la herramienta con un servicio de captura o un túnel.
¿Cómo se prueban los webhooks de Stripe?
Utilice la CLI de Stripe. Ejecute stripe listen --forward-to localhost:3000/webhooks para reenviar eventos de sandbox a su manejador y obtener un secreto de firma. Luego ejecute stripe trigger payment_intent.succeeded (o cualquier evento de stripe trigger --help) para disparar un evento de prueba real. La activación crea objetos de API respaldados y puede generar una cascada, por lo que payment_intent.succeeded también emite payment_intent.created.
¿Cómo se prueba un webhook de Slack?
Envíe un POST JSON a la URL del webhook entrante. La carga útil válida mínima es {"text":"Hello, world."}, enviada con un encabezado Content-type: application/json. Una prueba exitosa publica el mensaje en el canal configurado. Mantenga la URL en secreto, ya que Slack revoca las URL de webhook que se filtran.
¿Cómo se prueba una URL de webhook?
Envíe un POST de ejemplo a la URL y confirme que devuelve un estado de éxito y se comporta correctamente. La comprobación más rápida es un solo curl con un cuerpo representativo. Para una prueba real, capture primero una carga útil real, envíela con firmas válidas e inválidas, y afirme la respuesta y los efectos secundarios en lugar de solo verificar un 200.