Ir para o conteúdo
Promovaweb

Triggers e agendamentos

StayCloudVPS 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.

Montar minha VPS Agêntica

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

  1. A agenda fica dentro do flow
  2. Os seis tipos de trigger
  3. Schedule e as expressões cron
  4. Webhook com chave secreta
  5. Flow trigger encadeia rotinas
  6. Polling e Realtime para fontes externas
  7. Execução manual e pela API

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

TriggerO que dispara a execuçãoExemplo na stack
ScheduleUma expressão cron, com condições de calendário opcionais.O backup dos bancos às três da manhã, todos os dias.
FlowO fim de um ou mais flows anteriores num estado escolhido.A carga do Metabase depois que a sincronização do ERP termina com sucesso.
WebhookUma requisição HTTP vinda de fora.O n8n avisa que um cliente novo entrou e o Kestra prepara o banco dele.
PollingUm arquivo ou registro novo encontrado num sistema externo, checado em intervalos.Um arquivo novo num bucket S3 ou uma linha nova numa tabela.
RealtimeUm evento de uma fonte de streaming, com latência de milissegundos.Mensagens que chegam numa fila e precisam de reação imediata.
MCP ToolA chamada de um agente de IA a um flow publicado como ferramenta num servidor MCP.Um agente de código dispara a rotina de backup ou a carga de relatórios.

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.

  1. Scheduler

    Avalia as agendas e os outros triggers baseados em agenda. Só eles aparecem na aba Triggers e na API.

  2. Worker

    Roda os triggers de polling, que consultam o sistema externo em intervalos.

  3. Executor

    Trata os triggers do tipo Flow, quando outra execução termina no estado esperado.

  4. Webserver

    Recebe as chamadas HTTP dos triggers Webhook e cria a execução.

  5. Fila e execução

    Todos os caminhos terminam numa execução nova na fila, com estado, logs e saídas próprios.

A função do servidor responsável por cada tipo de trigger, segundo as páginas de triggers e de arquitetura da documentação.

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.