Webhooks e gatilhos

Um gatilho é como o Letaido percebe que algo aconteceu em outro aplicativo, em tempo real, sem precisar ficar verificando.

Quando um novo contato chega no HubSpot, quando alguém @menciona você no Slack, quando um negócio muda de estágio, o Letaido descobre imediatamente e age.

O que você pode fazer com isso

As coisas que as equipes configuram aqui se parecem com:

• Quando um novo contato do HubSpot for MQL, avalie-o em relação ao nosso ICP e publique o resultado em #mql-review.
• Quando alguém @mencionar o bot do Slack em #pmm-questions, responda com a voz da nossa marca.
• Quando um problema do Linear for rotulado como customer-facing, elabore um resumo público de um parágrafo e envie por DM para o líder de PMM.
• Quando uma versão do GitHub for publicada, elabore automaticamente um e-mail de lançamento e envie para o Notion para revisão.
• Quando uma reunião do Fathom terminar, extraia os itens de ação e adicione-os ao Linear.
• Quando um scraper do Apify terminar, inicie a próxima etapa de um pipeline.

Você descreve o gatilho e a ação em linguagem simples. O agente de IA configura a conexão, pede aprovação uma vez e depois é executado sozinho.

Como funciona nos bastidores

Existem dois tipos:

• Acionadores de conectores (preferencial). Uma assinatura tipada para um serviço de terceiros. A configuração é feita com uma chamada. A plataforma gerencia a assinatura, o segredo de assinatura, a lógica de repetição e a fila de eventos. Os eventos chegam com um esquema conhecido (Slack, GitHub, Linear, HubSpot, Fathom, Apify e outros).
• Webhooks ad-hoc. Para serviços sem um acionador de conector integrado ainda, o agente cria uma URL de webhook genérica, configura o terceiro para fazer POST nela e puxa os eventos para a mesma fila. O custo é um pouco mais de trabalho de análise, já que o esquema é o que o terceiro envia.

De qualquer forma, o agente escolhe o certo para você. Você não escolhe.

Como um evento flui

1. O serviço de terceiros faz POST para um URL público que a plataforma possui.
2. A plataforma verifica a assinatura, analisa o payload, enriquece-o (por exemplo, resolvendo IDs de canal para nomes no Slack) e o envia para uma fila interna.
3. Um consumidor (um aplicativo, um trabalho ou o agente de chat) pesquisa a fila com um cursor nomeado e processa eventos.
4. Cada evento é confirmado após o processamento; eventos não confirmados são reenviados se o consumidor falhar.

Os cursores são por consumidor, então um aplicativo de Console e um job podem monitorar os mesmos eventos sem interferir um no outro.

Confiável vs confirmação automática

• Confirmação automática (padrão). Lê eventos; eles desaparecem da fila imediatamente. Simples. Adequado para "acompanhar o feed, registrar em uma tabela".
• Confirmação manual. Lê eventos, processa-os e depois confirma explicitamente. Se o processamento falhar, o evento é reenviado. Use isso quando o efeito colateral (um e-mail, uma gravação no banco de dados, uma chamada de API downstream) não puder ser perdido.

Se você pedir ao agente "um fluxo de trabalho confiável", ele escolherá a confirmação manual por padrão.

Formatos comuns de perguntas

"Quando um novo contato do HubSpot for criado com estágio do ciclo de vida = marketingqualifiedlead, pontue a empresa em relação ao nosso ICP e publique o resultado em #mql-review."

O agente: 1. Inscreve-se no gatilho de contato criado do HubSpot. 2. Escreve um pequeno consumidor (aplicativo de console ou tarefa) que extrai o evento, chama o pontuador de ICP, publica no Slack por meio do conector do Slack. 3. Exibe tanto a aprovação de inscrição do HubSpot quanto a aprovação do Slack se for o primeiro uso dessas superfícies.

"Quando uma issue do GitHub for marcada com pmm-review, elabore um resumo de um parágrafo voltado para o cliente e envie para mim por DM."

"Quando alguém @mencionar o bot do Slack em #pmm-questions, responda usando a habilidade de voz da marca."

O que você vê na área de trabalho

Para cada assinatura ativa: - O conector e o tipo de evento. - O status do segredo de assinatura. - O URL público (para ad-hoc) ou a configuração do aplicativo de terceiros (para gatilhos de conector). - O consumidor que lê a fila.

Você pode pausar ou revogar uma assinatura pela interface da Área de trabalho. Revogar retorna 410 para quaisquer POSTs de entrada subsequentes.

Limites e casos extremos

• Nenhum evento é "consulta de distribuição do chat". Os acionadores são controlados pelo servidor. Se uma sessão de chat for fechada, os eventos ainda chegam e se acumulam na fila até que um consumidor os leia.
• A fila tem uma janela de retenção. Eventos não lidos com mais de alguns dias são descartados. Se você suspeitar que um consumidor estava off-line, verifique antes de presumir que um evento foi perdido.
• Os consumidores de sites públicos têm restrições extras. Os acionadores de superfície do site exigem revisão explícita por chamada (sem aprovação geral), porque um fluxo controlado pelo visitante é um risco de custo de distribuição.
• Os segredos de assinatura são armazenados, nunca exibidos. O agente de IA pode usá-los, mas não pode lê-los de volta.

Nos bastidores. Eventos de entrada atingem nginx → api-proxy → connectors service. O serviço verifica a assinatura em relação ao signing secret armazenado, executa o hook de enriquecimento do conector (por exemplo, o resolvedor de ID de usuário para nome de usuário do Slack) e, em seguida, grava uma linha em webhook_events. Os consumidores extraem via GET /webhooks/events?cursor=<name> com parâmetros opcionais provider e ack. Consumidores de confirmação manual fazem POST de volta para /webhooks/ack com through_id.