Webhooks

El sondeo de API implica que el sistema receptor pregunta repetidamente al sistema de origen "¿ha cambiado algo?" a intervalos fijos (cada 1 minuto, cada 5 minutos). Esto es ineficiente: la mayoría de las solicitudes de sondeo devuelven "sin cambios", consumiendo la cuota de API y creando latencia (la latencia máxima es igual al intervalo de sondeo). Los webhooks invierten el modelo: el sistema de origen notifica al receptor en el instante en que ocurre un evento, logrando una latencia casi nula sin llamadas a la API desperdiciadas. La limitación es la fiabilidad: los webhooks son "disparar y olvidar" por defecto — si el sistema receptor está inactivo, los eventos se pierden. Los sistemas de webhook bien diseñados añaden lógica de reintento con retroceso exponencial (intentando la entrega varias veces en intervalos crecientes) y registros de entrega (visibles en la interfaz de usuario del producto para que los clientes puedan inspeccionar si su endpoint recibió cada evento e investigar fallos).

Los fallos de webhook se encuentran entre los tickets de soporte de integración más complejos porque abarcan ambos lados de la integración. Escenarios comunes: (1) El endpoint no recibe eventos — verificar que la URL del endpoint sea accesible públicamente (no localhost), que el servidor aceptó el evento de prueba y que el tipo de evento esté suscrito. (2) No se devuelve una respuesta HTTP 200 — el servidor receptor debe devolver un estado HTTP 200 dentro de la ventana de tiempo de espera (típicamente 10–30 segundos); si tarda más, la plataforma de webhook marca la entrega como fallida incluso si el servidor procesó el evento. (3) Eventos duplicados — los consumidores de webhook bien diseñados deben ser idempotentes (procesar el mismo evento dos veces produce el mismo resultado que procesarlo una vez) utilizando el ID único del evento para detectar e ignorar duplicados. (4) Fallo en la verificación de firma — la mayoría de las API SaaS firman las cargas útiles de webhook con HMAC-SHA256 utilizando una clave secreta; el código del cliente debe verificar esta firma en cada evento recibido para prevenir ataques de webhook falsificados.

Product Ops colabora con Ingeniería para diseñar capacidades de webhook que minimicen la carga de soporte y maximicen la satisfacción del desarrollador. Mejores prácticas: cobertura de tipos de eventos (cada cambio de estado significativo en el producto debe tener un evento de webhook correspondiente); diseño de la carga útil del evento (las cargas útiles deben incluir todos los datos necesarios para actuar sobre el evento sin una llamada API de seguimiento — incluir el estado completo del objeto, no solo IDs que requieran una solicitud GET posterior); UI de registros de entrega (un registro de eventos buscable en el panel de control del producto donde los desarrolladores pueden ver cada evento disparado, su estado de entrega, la respuesta HTTP del servidor y un botón de "reentregar" para reintentos manuales); verificación de firma (firmar cada carga útil con HMAC-SHA256 y documentar claramente el proceso de verificación); y cargas útiles versionadas (cuando el esquema del evento deba cambiar, versionar la carga útil y soportar ambas versiones simultáneamente durante un período de transición — nunca realizar cambios que rompan la compatibilidad en una carga útil de webhook sin previo aviso).