Gatilhos dos fluxos: manual, agendamento e webhook
Todo fluxo do CollaborAI Enterprise começa por um gatilho. Veja como funcionam os três tipos, o que cada um entrega para o resto do fluxo e os cuidados com a URL do webhook.
Todo fluxo tem exatamente um gatilho, e ele é sempre o primeiro nó. O gatilho responde a uma pergunta só: quando o fluxo começa? No módulo Fluxos do CollaborAI Enterprise há três respostas: quando você clica, em um horário ou quando outro sistema chama.
Este artigo faz parte da série sobre o módulo. A visão geral explica o que é um fluxo, e o primeiro fluxo mostra a montagem passo a passo.
Os três, lado a lado
| Gatilho | Começa quando | O que entrega ao fluxo | Bom para |
|---|---|---|---|
| Execução manual | Você clica em Executar fluxo | Os dados que você informar na hora | Testes e tarefas sob demanda |
| Agendamento | Chega o dia e a hora | A data e o horário do disparo | Rotinas: relatórios, conferências, lembretes |
| Webhook | Outro sistema chama uma URL | O conteúdo que o sistema enviou | Integrações: formulário, ERP, loja |
Um fluxo novo nasce com Execução manual. Para trocar, passe o mouse sobre o gatilho e clique em Trocar gatilho. As ligações de saída são mantidas, então dá para montar e testar com o gatilho manual e só no fim trocar para o definitivo.
Execução manual
É o gatilho de quem está construindo. O fluxo roda quando você clica em Executar fluxo, na barra superior, ou usa Ctrl/Cmd + Enter.
No nó, você define um exemplo de entrada: os dados com que o fluxo começa. Ao executar, uma janela mostra esse exemplo, e você pode alterar antes de confirmar.
O gatilho manual também serve para fluxos que alguém dispara quando precisa, como “processar a lista deste mês”. Os valores digitados na janela ficam disponíveis no fluxo.
Agendamento
O fluxo roda sozinho, sem navegador aberto. As frequências prontas cobrem quase tudo:
- A cada hora, no minuto que você escolher.
- Diariamente, com hora e minuto.
- Semanalmente, escolhendo os dias da semana.
- Mensalmente, em um dia de 1 a 28, para existir em todos os meses.
- Personalizado, com uma expressão cron, para agendas fora do padrão. Um exemplo é
cron(0 8 ? * MON-FRI *), que roda às 8h de segunda a sexta.
Três coisas para saber:
- O menor intervalo é de uma hora. Não dá para rodar a cada cinco minutos.
- O fuso importa. O horário vale no fuso do nó. Se ele ficar vazio, vale o fuso das configurações do fluxo.
- Só roda com o fluxo ativo. O agendamento passa a valer quando você liga o interruptor da barra superior e para quando você desliga.
O gatilho entrega ao fluxo a data do disparo. É útil para montar textos como “Relatório de
{{ $json.scheduledDate }}” ou para buscar só os registros do dia.
Webhook
O webhook transforma o fluxo em um endereço que outros sistemas podem chamar. Um formulário foi enviado, um pedido foi aprovado, um chamado foi aberto: o sistema de origem faz uma chamada HTTP, e o fluxo começa.
Como configurar
- Troque o gatilho para Webhook e escolha o método. O mais comum é POST.
- Ative o fluxo. A URL só é gerada na ativação e aparece no próprio nó.
- Cadastre essa URL no sistema de origem, ou teste pelo terminal:
curl -X POST "<URL do webhook>" \
-H "Content-Type: application/json" \
-d '{"pedido": 123, "cliente": "Ana"}'A resposta chega na hora, com o código 202 e o identificador da execução. Ela confirma que o
fluxo começou e não espera o fluxo terminar. Se você precisa devolver um resultado ao sistema de
origem, o próprio fluxo pode fazer uma chamada de volta no último passo.
Como os dados chegam
O gatilho entrega um item com quatro partes: o método, os cabeçalhos, os parâmetros do endereço e o conteúdo enviado. No exemplo acima:
| Quero | Expressão |
|---|---|
| O número do pedido | {{ $json.body.pedido }} |
| O nome do cliente | {{ $json.body.cliente }} |
Um parâmetro do endereço (?origem=site) | {{ $json.query.origem }} |
Cuidados com a URL
- Trate a URL como uma senha. Ela carrega um token secreto, e quem tiver o endereço consegue iniciar o fluxo. Não cole em chat, documento público ou repositório de código.
- Fluxo desligado responde erro. Com o fluxo pausado, a chamada recebe
409. É assim que você interrompe uma integração sem apagar nada. - O método precisa bater. Chamadas com um método diferente do configurado são recebidas, mas não iniciam o fluxo.
- Há limite de tamanho e de frequência. O conteúdo aceita até 256 KB, e chamadas em excesso são recusadas. Para arquivos grandes, envie um link e baixe dentro do fluxo.
- Valide o que chega. Um nó Se logo depois do gatilho, conferindo se os campos obrigatórios vieram, evita que uma chamada malformada siga adiante.
E os gatilhos dos agentes?
Os agentes do CollaborAI também têm agendamento e webhook. A diferença está no que acontece depois do disparo:
- No agente, o gatilho entrega um pedido, e o agente decide o que fazer.
- No fluxo, o gatilho inicia uma sequência fixa de passos.
Use o gatilho do agente quando a tarefa é uma só e depende de interpretação, como “resuma as notícias do setor”. Use o fluxo quando há vários passos com regra, ou quando o resultado do agente precisa ser conferido, transformado ou entregue em mais de um lugar.
Qual escolher
- Está construindo ou testando? Manual.
- O processo acontece em horário fixo? Agendamento.
- O processo começa quando algo acontece em outro sistema? Webhook.
- Precisa dos dois, horário e evento? Faça dois fluxos. Cada fluxo tem um gatilho só.
O gatilho é a decisão mais simples do fluxo, e a que mais muda o uso dele. O próximo artigo da série entra no miolo: como decidir, repetir e juntar dados.
