Probar Webhooks: Guía para Desarrolladores

Los webhooks son la columna vertebral de la comunicación en tiempo real entre servicios. En lugar de consultar una API cada pocos segundos, un webhook permite que un servidor envíe datos a otro en el momento en que ocurre algo: un pago se completa, un commit se envía o un formulario se envía. Para los desarrolladores que crean integraciones, saber cómo probar webhooks localmente es una habilidad esencial.

A diferencia de una llamada REST API estándar que usted inicia desde su código, un webhook requiere que el servidor remitente alcance su endpoint. Durante el desarrollo local, su máquina no es accesible públicamente en internet. Esto significa que el servicio remitente no puede entregar el payload a localhost:3000. También necesita simular exactamente los encabezados, el formato de firma y la estructura JSON que envía el servicio real.

Varias herramientas cierran la brecha entre localhost e internet público. ngrok crea un túnel seguro a su servidor local y proporciona una URL HTTPS pública. Cloudflare Tunnel ofrece una capacidad similar integrada con la red Cloudflare. localtunnel es una alternativa ligera de código abierto. Cada herramienta reenvía las solicitudes webhook entrantes a su servidor de desarrollo local.

Un endpoint webhook expuesto a internet puede recibir solicitudes de cualquiera. Para verificar que una solicitud realmente proviene del remitente esperado, los webhooks de producción utilizan firmas HMAC. El servidor remitente calcula un hash del cuerpo del payload usando un secreto compartido y lo incluye en un encabezado como X-Hub-Signature-256 (GitHub) o Stripe-Signature (Stripe). Su servidor debe recalcular el hash y compararlo. Nunca confíe en datos de webhook sin verificar la firma primero.

Al probar webhooks desde una herramienta basada en el navegador, CORS se convierte en un obstáculo. Los navegadores bloquean respuestas de servidores que no permiten explícitamente su origen mediante el encabezado Access-Control-Allow-Origin. La mayoría de los endpoints webhook de producción están diseñados para recibir solicitudes de servidores backend, no de navegadores. Para evitar esto, enrute sus solicitudes de prueba a través de un proxy del lado del servidor o use nuestro comando cURL exportado.