Webhooks entrantes

Un webhook entrante es una URL que te da la plataforma y que un sistema externo llama cuando algo pasa de su lado. Del lado que envía está cualquier cosa capaz de hacer un HTTP POST: tu propia aplicación, un servicio de formularios, un procesador de pagos, una herramienta de agenda, un dispositivo IoT, un pipeline de CI, una plataforma de automatización. Del lado que recibe está un flujo de trabajo de AppBO que arranca en el momento en que llega la solicitud y puede leer los campos del cuerpo de la solicitud.

La razón para usar uno en lugar de la API es la dirección y la responsabilidad. Con la API, tu código es responsable de decidir cuándo actuar y de saber cuál es el estado actual de la plataforma. Con un webhook entrante, el sistema externo simplemente anuncia los hechos a medida que ocurren, y la lógica de automatización (buscar o crear el contacto, ramificar según un valor, enviar el mensaje, mover la oportunidad) vive dentro de la plataforma, donde alguien que no es desarrollador puede leerla y cambiarla. Esa división sobrevive a la rotación de personal mucho mejor que unas reglas de negocio enterradas en un proceso en segundo plano.

Los webhooks entrantes son la herramienta correcta cuando el evento de verdad tiene forma de evento: un pago se aprobó, un ticket se cerró, un envío salió del almacén, un prospecto llenó un formulario que alojas tú. Son la herramienta equivocada para cargas masivas de datos históricos, para todo lo que necesite una respuesta síncrona en el cuerpo de la respuesta y para los casos en que necesitas leer mucho estado de la plataforma antes de decidir: eso le corresponde a la API REST.

1. Crea en AppBO el flujo de trabajo que va a consumir el evento y configura su disparador como webhook entrante. Ponle un nombre que identifique al sistema que envía, porque la URL por sí sola no dice nada.
2. Copia la URL del webhook que genera el disparador. Trátala como un secreto: cualquiera que la tenga puede iniciar tu flujo con los datos que quiera.
3. Captura un ejemplo real de los datos (payload) antes de armar cualquier lógica. O apuntas primero el sistema que envía a un servicio de inspección de solicitudes, o envías un evento real y dejas que el disparador lo registre, para que la plataforma aprenda la estructura de campos de los datos a partir de datos reales y no de tus suposiciones.
4. Confirma el tipo de contenido del sistema que envía. Envía JSON con un encabezado Content-Type: application/json; un cuerpo codificado como formulario o un encabezado que no coincide es la razón más común de que los campos aparezcan vacíos en el flujo.
5. Mantén los datos planos cuando puedas. Los objetos y listas muy anidados son más difíciles de referenciar dentro de los pasos del flujo que una estructura de un solo nivel con claves explícitas, así que si controlas al emisor, aplana antes de enviar.
6. Incluye una clave de identidad estable en todos los datos: un email, un teléfono en formato E.164 o un identificador externo que también guardes en el contacto. Sin eso, el flujo no puede decidir de forma confiable si actualizar o crear.
7. Incluye un identificador de evento y una marca de tiempo del emisor. Vas a necesitar los dos para eliminar duplicados de los reintentos y para descartar eventos que llegan desordenados.
8. Agrega un secreto compartido que controles tú. Como el disparador acepta cualquier cosa que le envíen, el patrón práctico es un valor secreto dentro de los datos (o un encabezado que el flujo pueda leer) que el primer paso del flujo revisa, descartando todo lo que no coincida.
9. Mapea los campos de los datos al contacto. Decide campo por campo si el valor entrante debe sobrescribir, llenar solo cuando esté vacío o ignorarse.
10. Arma de forma explícita el paso de buscar o crear, basado en tu campo de identidad, antes de cualquier paso que envíe un mensaje o mueva una oportunidad.
11. Agrega una rama de protección para los eventos mal formados: sin clave de identidad, con el secreto incorrecto o con una marca de tiempo más vieja de lo que toleras. Mándalos a una rama que no hace nada o a una notificación, en lugar de dejar que caigan en el camino normal.
12. Verifica que la conexión esté activa enviando un evento de prueba y revisando el historial de ejecuciones del flujo. Confirma que entró, confirma que los valores de los campos se resolvieron y confirma que el contacto se encontró o se creó como esperabas.
13. Revisa lo que vio el emisor. Confirma que recibió un estado de éxito; si registró un tiempo de espera agotado o un error, va a reintentar, y necesitas saberlo antes de salir en vivo.
14. Corre la prueba de principio a fin una vez más con datos que deberían rechazarse y confirma que se rechazan.
15. Documenta la URL, la forma esperada de los datos y el equipo responsable en algún lugar donde tus colegas lo encuentren, y después activa el emisor en producción.

Del sistema externo a la plataforma

• El cuerpo de la solicitud HTTP, cuyos campos se vuelven valores que se pueden referenciar dentro del flujo de trabajo disparado.
• Campos de identidad que se usan para encontrar un contacto: email, teléfono o un identificador externo guardado en un campo personalizado.
• Datos del negocio: montos, valores de estado, nombres de productos o servicios, fechas, notas de texto libre.
• Metadatos que decidas enviar: identificador del evento, tipo de evento, marca de tiempo del emisor, nombre del sistema de origen.
• Encabezados de la solicitud, en la medida en que el disparador los exponga. Revisa qué está disponible antes de depender de un encabezado para autenticar.

De la plataforma de vuelta al sistema externo

• Un código de estado HTTP que confirma la recepción, y nada más de fondo.
• Ningún resultado del flujo, ningún identificador de contacto, ningún resultado de ramas. La respuesta es un acuse de recibo, no una respuesta de fondo.

Lo que no se mueve

• Cualquier cosa que el emisor no haya puesto en la solicitud. La plataforma no puede traer más detalle del sistema de origen por su cuenta. Si el flujo necesita más, tiene que llamar a la API de ese sistema en un paso posterior.
• Resultados síncronos. Si tu emisor necesita saber qué pasó, la plataforma tiene que llamarlo de vuelta por separado.
• Archivos adjuntos como parte de los datos del disparador. Envía en su lugar una URL que la plataforma pueda descargar.
• Un orden garantizado. Dos eventos enviados con milisegundos de diferencia se pueden procesar en cualquier orden.
• Eventos históricos de antes de que existiera el webhook. Las cargas de datos históricos le corresponden a la API REST.

Escenario: una herramienta de reservas alojada fuera de la plataforma tiene que crear o actualizar el contacto en AppBO e iniciar una secuencia de recordatorios cada vez que se reserva una sesión.

1. Creas un flujo de trabajo llamado Herramienta de reservas: sesión reservada, configuras su disparador como webhook entrante y copias la URL generada en tu almacén de secretos.
2. Configuras la herramienta de reservas para que haga un POST con su evento session.booked, con un cuerpo JSON que contiene event_id, event_type, occurred_at, email, phone, full_name, session_start, practitioner y un campo shared_secret.
3. Haces una reserva real para que el disparador capture un ejemplo en vivo y aprenda los nombres de los campos.
4. Un cliente reserva una sesión. La herramienta de reservas envía los datos por POST; la plataforma responde con un estado de éxito y el flujo arranca.
5. El paso uno compara shared_secret con el valor guardado. Coincide, así que la ejecución continúa; si no coincidiera, iría a una rama que termina el flujo.
6. El paso dos revisa que email venga incluido y que occurred_at esté dentro de la última hora. Los dos pasan.
7. El paso tres busca o crea el contacto por email. No existe ningún contacto, así que se crea uno con el nombre y el teléfono de los datos, con la etiqueta booking-tool y con session_start y practitioner escritos en campos personalizados.
8. El paso cuatro ramifica según practitioner para elegir la plantilla de recordatorio correcta.
9. El paso cinco envía un email de confirmación inmediato, después espera hasta veinticuatro horas antes de session_start y envía un recordatorio por SMS.
10. Una hora después, la herramienta de reservas reintenta el mismo evento porque su propio registro marcó un tiempo de espera agotado. El flujo vuelve a arrancar; el paso de protección ve un event_id que ya registró en el contacto y termina antes de que el email de confirmación se envíe por segunda vez.
11. El cliente reagenda. Llega un segundo evento con un event_id nuevo y un session_start posterior; el flujo encuentra el contacto existente por email, actualiza el campo personalizado y el recordatorio se recalcula según la fecha nueva.

Límites de uso

El endpoint de un webhook entrante no es una tubería de entrada ilimitada, y las ejecuciones de flujos de trabajo son un recurso medido en la cuenta. Un emisor que dispara miles de eventos de golpe (un proceso por lotes nocturno, una carga de datos históricos, un ciclo descontrolado) puede ser limitado o puede consumir una parte sorprendente del presupuesto de ejecuciones de la cuenta. Limita del lado del emisor y nunca uses un webhook entrante como mecanismo de importación masiva.

Reintentos e idempotencia

La plataforma no elimina duplicados por ti. La mayoría de los emisores reintentan cuando se agota el tiempo de espera o ante cualquier respuesta que no sea 2xx, y muchos reintentan ante una respuesta que simplemente tardó demasiado aunque haya funcionado, así que el mismo evento va a llegar dos veces. Envía siempre un identificador de evento, regístralo en el contacto o en una tabla de consulta y revísalo en el primer paso de protección. Sin eso, los reintentos producen emails duplicados, oportunidades duplicadas y cobros duplicados en todo lo que el flujo toque después.

Trampas al mapear campos

El disparador aprende la forma de los datos a partir de los ejemplos, así que un campo que no venía en tu ejemplo no se va a poder referenciar después. Incluye siempre las claves opcionales con valores vacíos en lugar de omitirlas. Los objetos anidados y las listas son incómodos de referenciar; aplánalos en el emisor. Los números que llegan como texto, las fechas en un formato inesperado y los teléfonos sin código de país son fallas de mapeo silenciosas que aparecen como campos vacíos o ramas que se saltan, no como errores.

Creación de contactos duplicados

Si la clave de identidad falta o no es consistente (email en unos eventos, teléfono en otros), un paso de buscar o crear va a crear un segundo contacto. Elige una clave, hazla obligatoria y rechaza los eventos que no la traigan en lugar de dejar que el flujo improvise.

Pruebas contra producción

Apunta el modo de prueba de tu emisor a un flujo en una subcuenta de prueba, nunca al flujo en vivo. Unos datos de prueba que llegan a un flujo en vivo con un teléfono real envían un mensaje real. Guarda las URL de prueba y de producción en entradas de secretos separadas y nómbralas sin ambigüedad.

Autenticación

La URL es lo único que hay entre tu flujo e internet abierto, y no es una firma. Agrega un secreto compartido en los datos y verifícalo en el primer paso. Cambia la URL del webhook si alguna vez se sube a un repositorio, se pega en un ticket o se comparte con un proveedor que se va, y recuerda que cambiarla significa volver a configurar a cada emisor.

Lo que se rompe con más frecuencia

• Un emisor que cambia la forma de sus datos en una nueva versión y deja vacíos, sin avisar, los campos de los que depende el flujo.
• Cuerpos codificados como formulario o un tipo de contenido JSON que falta.
• Eventos que llegan desordenados, así que un estado más viejo sobrescribe uno más nuevo.
• Un flujo editado directamente mientras le está entrando tráfico en vivo.
• La URL que se filtra y se usa para repetir solicitudes.
• Emisores que toman una respuesta lenta como una falla y reintentan sin fin.