Saltar al contenido

Conectividad e interoperabilidad

APIs, webhooks y eventos: contratos que sobreviven a fallos y versiones

Una API que funciona en la demostración no es todavía una integración fiable. En producción las peticiones expiran, los webhooks llegan dos veces o desordenados, un consumidor sigue usando la versión de hace un año y alguien pregunta por qué un pedido no se actualizó el martes. Esta página recoge las decisiones de diseño de la interfaz en sí: cuándo conviene una llamada síncrona y cuándo un mensaje, cuándo encaja GraphQL frente a REST, cómo recibir webhooks sin perderlos, cómo hacer que repetir una operación sea seguro, cómo versionar y cómo seguir el rastro de una petición entre varios servicios. La arquitectura de eventos a gran escala se trata aparte, en su capacidad.
Plantear un proyectoVer escenarios
Recorrido de un webhook entrante hasta su efecto en el negocioEsquema ilustrativo

  1. 01 · Recepción

    • Endpoint HTTPS dedicado
    • Verificación de firma y marca de tiempo

  2. 02 · Persistencia

    • Evento original guardado
    • Respuesta inmediata al emisor

  3. 03 · Procesamiento

    • Cola con reintentos y espera creciente
    • Comprobación de clave de idempotencia
    • Reordenación por estado y fecha de origen

  4. 04 · Efecto y traza

    • Pedido o cobro actualizado
    • Identificador de correlación en registros
    • Cola de fallidos con revisión humana

El problema

Por qué hay que decidirlo bien

Los fallos de integración más caros no son los que paran el sistema, sino los silenciosos: un cobro registrado dos veces porque el cliente reintentó, un estado de envío que se pierde porque el webhook llegó mientras se desplegaba una versión, un campo renombrado que deja de rellenarse en un socio sin que nadie lo note. Cada uno exige horas de investigación y, a menudo, correcciones manuales. El problema de negocio es poder confiar en que lo que dice un sistema coincide con lo que ocurrió y, si no, poder explicarlo con datos.

Escenarios

Situaciones en las que se plantea

Ejemplos de lo que se podría diseñar. No describen proyectos realizados.

  • 01

    Recepción de webhooks de una pasarela de pago

    El endpoint verifica la firma y la marca de tiempo, guarda el evento tal como llegó y responde enseguida. El procesamiento ocurre después, desde una cola, y tolera que el aviso de reembolso llegue antes que el de cobro confirmado.

  • 02

    API para una aplicación móvil y para socios externos

    La misma lógica se expone con recursos REST versionados, autenticación por cliente y límites de uso. La aplicación móvil y el socio consumen contratos distintos, de modo que mejorar la app no obliga a coordinar un cambio con el socio.

  • 03

    GraphQL para pantallas con necesidades variadas

    Un panel interno combina pedidos, clientes e incidencias de formas distintas en cada vista. GraphQL evita multiplicar endpoints a medida, a cambio de limitar la complejidad de las consultas, controlar permisos por campo y renunciar a parte del cacheo HTTP sencillo.

  • 04

    Publicar un evento sin perderlo ni inventarlo

    Al confirmar un pedido, el cambio y el evento que lo anuncia se guardan en la misma transacción de base de datos; un proceso aparte lo publica después. Así no hay pedidos confirmados sin evento ni eventos de pedidos que nunca se guardaron.

  • 05

    Seguir una petición a través de cuatro servicios

    Un identificador de correlación nace en la primera petición y viaja en cabeceras y mensajes. Cuando un cliente reclama, se puede reconstruir qué servicio recibió qué, cuánto tardó y dónde se quedó, sin cruzar registros a mano por hora aproximada.

Decisiones técnicas

Qué hay que decidir y con qué criterio

  1. 01

    Síncrono o asíncrono

    Una llamada síncrona tiene sentido cuando quien pide necesita la respuesta para continuar, como una validación de stock. Si basta con saber que se hará, un mensaje en cola desacopla tiempos y absorbe caídas del destino.

  2. 02

    Estilo de API

    REST con recursos bien definidos es la opción por defecto y la más fácil de cachear, documentar y proteger. GraphQL encaja cuando muchos consumidores necesitan combinaciones distintas de los mismos datos y hay capacidad para gobernar su esquema.

  3. 03

    Idempotencia

    Toda operación que pueda repetirse lleva una clave única, enviada por el cliente o derivada del mensaje, y el receptor guarda las ya procesadas. Repetir una petición devuelve el mismo resultado en lugar de crear un segundo registro.

  4. 04

    Reintentos y mensajes fallidos

    Reintentos con espera creciente y algo de aleatoriedad, un número máximo de intentos y una cola de mensajes fallidos que alguien revisa. Se distingue entre errores transitorios, que se reintentan, y errores de datos, que no mejorarán repitiendo.

  5. 05

    Versionado y retirada

    Se decide qué cambios son compatibles, como añadir un campo opcional, y cuáles exigen versión nueva. Cada versión antigua tiene fecha de retirada anunciada y se mide quién la sigue usando antes de apagarla.

  6. 06

    Trazabilidad y observabilidad

    Identificador de correlación, registro estructurado de cada intercambio con su resultado, métricas de latencia y error por endpoint y alertas sobre colas que crecen. Sin esto, cada incidencia empieza por adivinar.

Riesgos y límites

Lo que conviene tener presente

  • La entrega «exactamente una vez» no existe de forma general en sistemas distribuidos; se diseña para entregas repetidas y se deduplica en el receptor.
  • Los webhooks de terceros pueden llegar desordenados, retrasados o no llegar; conviene una consulta periódica de conciliación como red de seguridad.
  • Reintentar sin límite contra un servicio caído agrava su caída y puede agotar cuotas; los reintentos necesitan freno.
  • Guardar cuerpos completos de mensajes ayuda a auditar, pero puede almacenar datos personales o secretos; se decide qué se guarda, cuánto tiempo y con qué acceso.

Preguntas frecuentes

¿Cómo sabemos si un webhook se ha perdido?

No siempre se puede saber desde el receptor. Por eso, además de recibir avisos, se programa una consulta periódica a la API del emisor que compara estados y recupera lo que falte. Muchos proveedores ofrecen también un registro de entregas fallidas que conviene vigilar.

¿Merece la pena pasar de REST a GraphQL?

Solo si el problema real es que los consumidores necesitan muchas combinaciones distintas de datos y los endpoints se multiplican. Si la API tiene pocos consumidores y operaciones claras, REST suele ser más sencillo de operar, proteger y cachear.

¿Cuánto tiempo hay que mantener una versión antigua de una API?

El que se pacte con sus consumidores, en función de su capacidad para migrar. Lo importante es anunciarlo con fecha, medir el uso real de la versión antigua y no retirarla mientras haya tráfico relevante sin haber avisado a quien lo genera.

Sectores, capacidades y lecturas relacionadas

Sectores donde se plantea

Capacidades relacionadas

Para profundizar

Más en integraciones

Cuéntanos qué sistemas deben hablar entre sí y qué falla hoy

Ninguna modalidad está disponible por defecto en todos los proyectos: se elige tras evaluar requisitos, sistemas existentes y riesgos.

Plantear un proyecto

Sin compromiso de aceptación: estudiamos cada caso antes de proponer nada. Cómo tratamos la información que compartes.