Triggers e agendamentos
VPS Agêntica
Uma VPS para os seus agentes trabalharem dia e noite
Instale o SetupVibe Desktop numa VPS da StayCloud em São Paulo, com acesso root e disco NVMe. Deixe Claude Code, Codex e OpenCode rodando no tmux ou no Herdr e feche o notebook sem interromper nada.
Link de parceiro da Promovaweb.
Black Friday até 30/11
30%off
nos 2 primeiros meses do plano mensal da VPS
- Backup diário grátis para sempre
- Servidores em São Paulo no datacenter da Ascenty
- Datacenter Tier III manutenção sem parada
- Acesso root com disco SSD NVMe
- Réplica do backup em Ashburn, nos EUA
Um trigger é o mecanismo que inicia uma execução do flow sozinho, sem ninguém clicar em Executar. O Kestra tem seis tipos: Schedule para agendas cron, Flow para o fim de outro flow, Webhook para chamadas HTTP, Polling para novidades em sistemas externos, Realtime para eventos de streaming e MCP Tool para expor o flow como ferramenta a um agente de IA.
Sumário da página
A agenda fica dentro do flow
No crontab, a agenda de um script vive num arquivo do sistema, longe do script. O script não diz quando roda. O crontab não diz o que cada linha faz. No Kestra, a agenda é uma propriedade do próprio flow, na lista triggers. Abra o arquivo e você vê, no mesmo lugar, o que a rotina faz e quando ela dispara.
Um flow pode ter vários triggers. A mesma rotina de relatório pode rodar toda segunda às oito, pela agenda. Ela também roda quando o n8n chamar o webhook dela depois de fechar o mês de um cliente. Cada disparo cria uma execução separada, com o próprio estado e os próprios logs.
Os seis tipos de trigger
Schedule e as expressões cron
O trigger Schedule usa a sintaxe cron padrão, uma sequência de campos de tempo numa string. A documentação mostra 0 9 * * * para uma execução diária às nove horas e aceita atalhos como @hourly e @daily. O formato é o mesmo do crontab, então a migração de uma rotina antiga começa copiando a expressão.
As condições de calendário entram na expressão when do trigger. Funções como isWeekend(), isPublicHoliday() e dayOfWeek() evitam complicar a expressão cron com casos especiais. Na 2.0, o when substituiu a lista de condições dos triggers.
O Schedule também resolve um problema que o cron ignora: as execuções perdidas. Se o servidor ficou desligado durante a madrugada, o backfill reexecuta os intervalos de agenda perdidos entre uma data de início e uma de fim. Apagar um backfill cancela só as execuções de recuperação que ainda não rodaram. Apagar o trigger remove o estado guardado dele, inclusive o backfill, mas deixa a definição do trigger no flow.
Scheduler
Avalia as agendas e os outros triggers baseados em agenda. Só eles aparecem na aba Triggers e na API.
Worker
Roda os triggers de polling, que consultam o sistema externo em intervalos.
Executor
Trata os triggers do tipo Flow, quando outra execução termina no estado esperado.
Webserver
Recebe as chamadas HTTP dos triggers Webhook e cria a execução.
Fila e execução
Todos os caminhos terminam numa execução nova na fila, com estado, logs e saídas próprios.
Webhook com chave secreta
O trigger Webhook cria um endereço HTTP para o flow. A URL segue o formato /api/v1/main/executions/webhook/{namespace}/{flowId}/{key}. A chave key é obrigatória e funciona como segredo: a documentação recomenda guardá-la nos segredos do Kestra, fora do YAML do flow. Nas edições Enterprise e Cloud, o trecho main é trocado pelo identificador do tenant.
O Kestra aceita GET, POST e PUT nesse endereço. Por padrão, ele responde na hora, sem esperar o flow terminar, o que atende o sistema que só precisa avisar um evento. Com wait: true, a conexão fica aberta até o flow acabar ou o tempo limite do trigger vencer. O sistema que chamou recebe o resultado. O corpo da requisição chega ao flow e pode ser lido pelas tasks.
Flow trigger encadeia rotinas
O trigger Flow inicia um flow quando outros terminam num estado escolhido. Ele resolve o encadeamento sem amarrar os arquivos: a sincronização do ERP não precisa saber que existe uma carga de dashboards depois dela. A carga declara que roda quando a sincronização terminar com sucesso. Se amanhã surgir uma terceira rotina interessada no mesmo evento, ela declara o próprio trigger. A sincronização continua igual.
A diferença para o Subflow está na direção. No subflow, o flow pai chama o filho e pode esperar o resultado. No Flow trigger, o flow seguinte observa o anterior. Os dois são independentes.
Polling e Realtime para fontes externas
Os triggers de polling verificam uma fonte externa em intervalos e disparam quando encontram algo novo. Eles vêm dos plugins: o plugin de um banco consulta uma tabela. O plugin de um bucket lista arquivos. O worker roda essas verificações, como roda as tasks.
O trigger Realtime reage a eventos de streaming com latência de milissegundos. Ele atende filas de mensagens e fontes que publicam eventos sem parar. Para as rotinas de uma agência, Schedule, Webhook e Flow cobrem a maior parte dos casos. Polling e Realtime entram quando a origem do evento é um sistema que não chama webhook.
Execução manual e pela API
Os triggers não são a única porta. O botão Executar da página do flow dispara uma execução na hora, com o formulário dos inputs. A API também inicia execuções diretamente, o que serve para um script de deploy ou para outra ferramenta que prefere chamar a API em vez do webhook. Em todos os casos, o resultado é o mesmo: uma execução registrada, que o hub de execuções, logs e falhas explica em detalhe.
Antes disso, vale entender de onde vêm as tasks que o trigger coloca para rodar. O hub de plugins e scripts mostra o catálogo e os task runners.