Cómo integrar webhooks en un SaaS sin perder eventos ni duplicar acciones

Una suscripción cambia de plan en un sistema externo, pero el SaaS no actualiza el acceso del cliente. Horas después llega el mismo aviso otra vez y se aplica un ajuste duplicado. Para quien usa el producto, ambos fallos parecen errores del SaaS, aunque el problema esté en la integración. Por eso, integrar webhooks en un SaaS exige diseñar qué ocurre antes, durante y después de recibir cada evento.

Un webhook es una notificación enviada por un sistema a otro cuando sucede algo. Evita consultar continuamente si hubo cambios, pero no garantiza por sí solo que cada aviso llegue una sola vez, en orden o cuando el receptor esté disponible. La meta práctica no es prometer una entrega perfecta: es poder recuperar eventos pendientes, impedir efectos duplicados y detectar las excepciones que requieren intervención.

Definir el contrato y el responsable de cada cambio

Antes de crear el endpoint, dibuja un flujo concreto: qué sistema origina el cambio, qué evento emite, qué dato identifica al cliente y qué acción debe ejecutar el SaaS. Decide también cuál es la fuente de verdad. Si el sistema externo determina el estado de una suscripción, un webhook puede ser la señal para consultar o actualizar ese estado; no tiene por qué ser la única prueba de cómo quedó.

Documenta los tipos de evento, identificadores, versión del esquema y reglas de negocio. Diferencia «evento recibido» de «acción completada»: una notificación de cambio de plan puede llegar correctamente aunque la actualización interna falle. Asigna responsables para modificar el contrato, atender errores y resolver discrepancias. Sin esa propiedad operativa, una cola de fallos acaba convirtiéndose en un archivo que nadie revisa.

Elige un primer caso acotado, con un efecto fácil de comprobar. No conectes a la vez todos los eventos de facturación, permisos y comunicaciones. Cuantas más acciones dependen de un aviso, más difícil resulta entender qué falló y repetir únicamente la parte pendiente.

Recibir rápido, conservar primero, procesar después

El endpoint debe autenticar el origen, validar lo imprescindible y guardar el evento de forma duradera antes de confirmar su recepción. Según el proveedor, esto puede incluir verificar una firma sobre el cuerpo original y comprobar una marca temporal dentro de una ventana razonable. Usa HTTPS, protege los secretos y planifica su rotación. No registres cargas completas con datos sensibles solo para facilitar la depuración.

Tras persistir el aviso, un proceso separado puede ejecutar la lógica de negocio. Así, una operación lenta o un sistema interno temporalmente caído no bloquea la respuesta al emisor. Si la persistencia falla, no confirmes el webhook como recibido: permite que el proveedor reintente conforme a su contrato. Si el proveedor no ofrece reintentos fiables, hará falta otra vía de recuperación, como una conciliación periódica con su API cuando esté disponible.

Conviene conservar un registro de recepción con identificador, origen, cliente o ámbito, tipo de evento, estado y fechas de los intentos. El contenido almacenado y su retención deben limitarse a lo necesario para procesar y auditar el flujo. Una respuesta correcta del endpoint solo significa «aceptado para procesar», no necesariamente «cambio aplicado».

Reintentos e idempotencia sin efectos secundarios repetidos

Los reintentos son necesarios porque las redes y los servicios fallan. Pero un emisor puede repetir un aviso incluso después de que se haya procesado: quizá no recibió la confirmación. Diseña, por tanto, para entregas repetidas. Guarda una clave única que combine el origen y el identificador estable del evento; si hay varios clientes o espacios de trabajo, incorpora ese ámbito. Registra y comprueba esa clave de forma atómica para que dos trabajadores simultáneos no ejecuten la misma acción.

La deduplicación del aviso no siempre basta. Si una acción crea un cargo, concede acceso o envía una comunicación, define también una clave de idempotencia para ese efecto de negocio. Evita marcar un evento como completado antes de confirmar la acción: un fallo entre ambos pasos dejaría trabajo perdido. Cuando intervienen varias bases de datos o servicios, diseña estados explícitos y una forma segura de reanudar o conciliar; una transacción local no convierte todo el flujo en una operación única.

Aplica reintentos con esperas crecientes y un límite. Los errores temporales merecen otra oportunidad; una firma inválida o un esquema incompatible necesitan una ruta distinta. Envía los fallos persistentes a una cola o estado de revisión con contexto suficiente para investigar y repetir el procesamiento sin volver a ejecutar efectos ya completados. Si los eventos pueden llegar desordenados, usa versiones del objeto o consulta su estado vigente antes de aplicar un cambio antiguo.

Supervisar, probar y ampliar con cautela

Una integración no está lista solo porque el caso feliz funcione. Prueba avisos repetidos, simultáneos, retrasados y fuera de orden; respuestas perdidas; caídas del almacenamiento; cambios de esquema y secretos rotados. Comprueba tanto el resultado de negocio como el registro técnico. Si el SaaS también publica webhooks, aplica principios similares al envío: registra el cambio y la intención de notificar de forma consistente, entrega con reintentos y proporciona identificadores para que el receptor pueda deduplicar.

En producción, observa eventos recibidos, pendientes, completados y apartados para revisión, además del tiempo hasta completar la acción. Establece alertas para acumulaciones y fallos persistentes, con una persona responsable de investigarlos. Contrasta periódicamente el estado del SaaS con la fuente de verdad cuando sea posible: las métricas de entrega no detectan por sí solas todas las discrepancias de negocio.

Empieza con un tipo de evento y un grupo limitado de clientes o cuentas internas. Define de antemano cómo pausar el procesamiento, corregir datos y reprocesar con seguridad. Amplía el alcance solo cuando el equipo pueda explicar los fallos observados y demostrar que recupera el flujo sin duplicar acciones.

Si estás definiendo una integración de este tipo, Cibercoding puede ayudarte a revisar el contrato, los puntos de control y el alcance de una primera puesta en producción.