Webhooks y triggers

Un trigger es la forma en que Letaido detecta que algo ha sucedido en otra aplicación, en tiempo real, sin tener que estar comprobándolo constantemente.

Cuando un nuevo contacto llega a HubSpot, cuando alguien te @menciona en Slack, cuando un acuerdo cambia de etapa, Letaido se entera inmediatamente y actúa.

Qué puedes hacer con esto

Las cosas que los equipos configuran aquí se ven así:

• Cuando un nuevo contacto de HubSpot sea MQL, puntúalo según nuestro ICP y publica el resultado en #mql-review.
• Cuando alguien @mencione al bot de Slack en #pmm-questions, responde con la voz de nuestra marca.
• Cuando una incidencia de Linear se etiquete como customer-facing, redacta un resumen público de un párrafo y envíalo por DM al responsable de PMM.
• Cuando se publique un lanzamiento en GitHub, redacta automáticamente un correo de lanzamiento y envíalo a Notion para revisión.
• Cuando finalice una reunión de Fathom, extrae los elementos de acción y añádelos a Linear.
• Cuando un scraper de Apify termine, inicia la siguiente etapa del pipeline.

Describes el activador y la acción en lenguaje sencillo. El agente configura la conexión, pide aprobación una vez y luego se ejecuta por sí solo.

Cómo funciona internamente

Hay dos versiones:

• Activadores de conectores (preferidos). Una suscripción tipada a un servicio de terceros. La configuración es una sola llamada. La plataforma gestiona la suscripción, el secreto de firma, la lógica de reintentos y la cola de eventos. Los eventos llegan con un esquema conocido (Slack, GitHub, Linear, HubSpot, Fathom, Apify y otros).
• Webhooks ad-hoc. Para servicios sin un activador de conector integrado todavía, el agente genera una URL de webhook genérica, configura el tercero para que haga POST a ella y extrae los eventos a la misma cola. El coste es un poco más de trabajo de análisis, ya que el esquema es lo que sea que envíe el tercero.

De cualquier forma, el agente elige el correcto por ti. Tú no eliges.

Cómo fluye un evento

1. El servicio de terceros hace POST a una URL pública que posee la plataforma.
2. La plataforma verifica la firma, analiza la carga útil, la enriquece (por ejemplo, resolviendo los ID de canal a nombres para Slack) y la envía a una cola interna.
3. Un consumidor (una aplicación, un trabajo o el agente de chat) sondea la cola con un cursor con nombre y procesa los eventos.
4. Cada evento se confirma después del procesamiento; los eventos no confirmados se vuelven a entregar si el consumidor falla.

Los cursores son por consumidor, por lo que una aplicación de consola y un trabajo pueden observar los mismos eventos sin interferir entre sí.

Fiable vs confirmación automática

• Auto-ack (predeterminado). Lee eventos; desaparecen de la cola inmediatamente. Simple. Perfecto para "seguir el feed, registrar en una tabla".
• Ack manual. Lee eventos, procésalos y luego confírmalos explícitamente. Si el procesamiento falla, el evento se vuelve a entregar. Usa esto cuando el efecto secundario (un correo electrónico, una escritura en la base de datos, una llamada a una API externa) no debe perderse.

Si le pides al agente "un flujo de trabajo confiable", elige la confirmación manual de forma predeterminada.

Formas comunes de preguntar

"Cuando se crea un nuevo contacto de HubSpot con lifecycle stage = marketingqualifiedlead, puntúa la empresa según nuestro ICP y publica el resultado en #mql-review."

El agente: 1. Se suscribe al activador de contacto creado en HubSpot. 2. Escribe un pequeño consumidor (aplicación de consola o trabajo) que extrae el evento, llama al puntuador de ICP, publica en Slack a través del conector de Slack. 3. Muestra tanto la aprobación de suscripción de HubSpot como la aprobación de Slack si es la primera vez que se utilizan esas superficies.

"Cuando una incidencia de GitHub se etiquete como pmm-review, redacta un resumen de un párrafo orientado al cliente y envíamelo por mensaje directo."

"Cuando alguien @menciona el bot de Slack en #pmm-questions, responde usando la habilidad de voz de marca".

Lo que ves en el espacio de trabajo

Para cada suscripción activa: - El conector y el tipo de evento. - El estado del secreto de firma. - La URL pública (para ad-hoc) o la configuración de la aplicación de terceros (para activadores de conector). - El consumidor que lee la cola.

Puedes pausar o revocar una suscripción desde la interfaz de usuario del Espacio de trabajo. Revocar devuelve 410 a cualquier POST entrante posterior.

Límites y casos extremos

• Ningún evento es nunca "consulta desglosada desde el chat". Los activadores están controlados por el servidor. Si se cierra una sesión de chat, los eventos siguen llegando y se acumulan en la cola hasta que un consumidor los lee.
• La cola tiene una ventana de retención. Los eventos no leídos de más de unos días se eliminan. Si sospechas que un consumidor estuvo desconectado, compruébalo antes de asumir que se perdió un evento.
• Los consumidores del sitio público tienen restricciones adicionales. Los activadores de superficie del sitio requieren revisión explícita por llamada (sin aprobación general), porque un flujo controlado por el visitante es un riesgo de coste de consulta desglosada.
• Los secretos de firma se almacenan, nunca se muestran. El agente puede usarlos pero no puede volver a leerlos.

Bajo el capó. Los eventos entrantes llegan a nginx → api-proxy → servicio de conectores. El servicio verifica la firma contra el secreto de firma almacenado, ejecuta el hook de enriquecimiento del conector (por ejemplo, el resolutor de ID de usuario a nombre de usuario de Slack) y luego escribe una fila en webhook_events. Los consumidores extraen mediante GET /webhooks/events?cursor=<name> con parámetros opcionales provider y ack. Los consumidores de confirmación manual hacen POST de vuelta a /webhooks/ack con through_id.