Automações, rotinas e webhooks

O que roda sozinho no seu site

Q: A automação de horário gasta tokens?

Sim. O campo Mensagem da automação é enviado para a sessão escolhida e o Harness processa como se você tivesse digitado: cada disparo gasta tokens. Rotina e webhook rodam código, sem IA. O gasto aparece em 📊 Consumo de Tokens e o administrador pode definir um limite mensal por usuário em Usuários.

Q: Dá para ser avisado quando a execução falha?

A automação tem o campo Avisos, com e-mail e/ou Telegram, no modo sempre (com a resposta) ou só se der problema. A rotina não tem esse campo: o registro dela é o log em logger/thread/ / /, que o Harness lê com read_app_logs e mostra com run_thread_once.

Tem tarefa que ninguém deveria fazer na mão: mandar o lembrete da véspera, resumir os pedidos da semana, registrar o pagamento que caiu de madrugada. Na FlexPage isso se resolve de três formas diferentes — e cada uma serve para um tipo de trabalho. A automação manda uma mensagem para o Harness num horário marcado; a rotina é um programa que o servidor roda sozinho, sem IA; o webhook é um endereço do site que outro sistema chama para avisar que algo aconteceu.

Quero automatizar Ver a lição 13 do guia

Rotina roda sem IA — não gasta tokens Aviso por e-mail ou Telegram quando falha Webhook com endereço próprio no seu domínio

Três mecanismos

Confundir os três é o erro mais comum

O material da própria plataforma faz questão de separá-los: a automação trabalha com IA e gasta tokens; a rotina é código que roda sem IA; o webhook não trabalha — ele recebe o aviso de outro sistema.

Mecanismo 1

⏰ Automação de horário

Você deixa um bilhete para o Harness: uma mensagem que é enviada para uma sessão automaticamente, num horário marcado. “Toda segunda às 8h, faça isto.” Quem lê e executa é a IA — por isso cada disparo gasta tokens.

⏰ Automações · dentro do painel

Mecanismo 2

⏱️ Rotina

Um programa que o servidor roda sozinho, mais ou menos a cada minuto, sem IA. O Harness escreve uma vez; depois disso ninguém precisa pedir nada. Serve para tarefa repetitiva e simples: lembrete, relatório, cobrança, fila.

pasta thread/ · ex.: thread/agendamento-whatsapp.js

Mecanismo 3

🔗 Webhook

Um endereço do site que outro sistema chama para avisar algo — “o pagamento caiu”, “o pedido foi pago”, “chegou resposta de formulário”. O arquivo em script/ é o endereço; quem bate na porta é o sistema de fora.

pasta script/ · ex.: script/webhook-pagamento.js → /webhook-pagamento

Mecanismo	Para que serve	Quem dispara	Usa IA?	Onde fica
⏰ Automação	Mandar uma mensagem para uma sessão do Harness em horário marcado: resumo, conferência, lembrete de tarefa interna.	O relógio do painel, no horário e na repetição que você configurou.	Sim — cada execução gasta tokens.	Marcada em ⏰ Automações, apontando para uma sessão. Não é arquivo.
⏱️ Rotina	Trabalho repetitivo e simples, sem julgamento de IA: lembrete no WhatsApp, confirmação, relatório, backup, cobrança, processar fila, sincronizar.	O servidor, a cada ciclo (mais ou menos a cada minuto). O próprio programa decide se já é hora.	Não — roda código, sem IA.	Pasta `thread/`. Ex.: `thread/agendamento-whatsapp.js` envia confirmação, lembretes de 24h e 1h e mensagem pós-atendimento.
🔗 Webhook	Receber o aviso de um sistema de fora e fazer algo com ele: gateway de pagamento, loja virtual, formulário, CRM.	O outro sistema, quando o fato acontece. Pode repetir a entrega.	Não — o script recebe, valida, guarda e responde.	Pasta `script/`. O nome do arquivo vira o caminho: `script/api.js` → `/api`.

Qual escolher? Para tarefa repetitiva e simples, a recomendação do material é a rotina: ela não consome tokens e não depende de ninguém pedir. A automação entra quando o trabalho precisa de IA — ler, resumir, comparar, decidir com base em arquivos. E o webhook só existe quando há um sistema de fora avisando.

Mecanismo 1 · ⏰ no painel

Automação com hora marcada

A tela chama isso de automação: uma mensagem enviada a uma sessão automaticamente. O exemplo do guia é uma barbearia que quer o resumo das reclamações da semana toda segunda às 8h.

08:00

Sessão “Relatórios da barbearia”

“Leia as mensagens de suporte da semana em sandbox/support e me resuma as reclamações mais comuns.”

12:00

Outro horário no mesmo dia

O campo Horários aceita um ou vários no mesmo dia — 08:00, 12:00 e 17:30 no exemplo do guia.

17:30

Repetição: dias úteis

As opções são: uma vez, todo dia, dias úteis, toda semana ou a cada N horas.

31/12

Até (data final)

Depois dessa data, a automação para sozinha.

Aviso por e-mail Aviso por Telegram Sempre (com a resposta) ou só se der problema

Campo	O que aceita
Sessão	A conversa que vai receber a mensagem (ex.: “Relatórios da barbearia”).
Mensagem	O texto que o Harness recebe, como se você tivesse digitado na caixa de mensagem.
Repetição	Uma vez, todo dia, dias úteis, toda semana ou a cada N horas.
Horários	Um ou vários no mesmo dia: 08:00, 12:00, 17:30.
Até (data final)	31/12 — depois disso, ela para.
Avisos	E-mail e/ou Telegram, sempre (com a resposta) ou só se der problema.

Configure os canais antes: em 🔔 Canais de aviso, no Telegram você cola o token do seu bot, manda uma mensagem ao bot e clica em 🔍 Detectar para achar o seu chat; no e-mail, escolhe o provedor e a senha de app.

Teste o aviso: 📨 Enviar teste confere se a mensagem chega antes de você depender dela.

Teste a automação: ▶ Rodar agora dispara na hora, sem esperar o horário.

O Harness também sugere: se você pedir “me lembre na sexta de revisar os preços”, ele propõe o agendamento e você aprova. Um ajuste depois (“mude para as 9h”, “avise também no Telegram”) gera um novo agendamento de mesmo nome, que substitui o anterior — sem duplicata para apagar.

Cada disparo gasta tokens. A automação manda a mensagem para o Harness, que processa com IA como em qualquer conversa. O consumo aparece em 📊 Consumo de Tokens, no menu do painel, e o administrador pode definir um limite mensal por usuário em Usuários. Se a tarefa é repetitiva e simples, a rotina resolve sem esse custo.

O e-mail de aviso caiu no spam? Marque como “Não é spam” e crie um filtro para o assunto [FlexPage] com “Nunca enviar para spam”.

Mecanismo 2 · pasta thread/

Rotina: o programa que roda sem IA

Uma rotina é um programa guardado na pasta thread/. O servidor o executa sozinho, mais ou menos a cada minuto, mesmo com o painel fechado — não há cron para configurar, não há botão para apertar. O Harness escreve uma vez, numa sessão do tipo ⏱️ Rotina, e depois ela trabalha sozinha.

1. Ciclo do servidorO servidor acorda as rotinas a cada ciclo (padrão de 60 segundos) e relê a pasta: arquivo novo entra em execução sozinho.

2. A rotina decideEla mesma confere se já deu a hora, guardando a marca da última execução. Se não deu, sai sem fazer nada.

3. Se deu a hora, trabalhaProcessa um número limitado de itens por rodada e escreve no log o que fez. O resto fica para o próximo ciclo.

Lembrete e confirmação: o exemplo do guia é thread/agendamento-whatsapp.js, que envia a confirmação, os lembretes de 24h e 1h antes do corte e a mensagem pós-atendimento. Na tela de tipos de sessão, o exemplo é “lembrete no WhatsApp 1h antes do corte”.

Relatório, backup e cobrança: entre as tarefas que o site descreve como “coisas que rodam sozinhas de tempos em tempos” estão lembretes, relatórios, backups e cobranças. Também entram processar fila, sincronizar com outro sistema e limpar registros antigos.

Sem visitante: uma rotina não tem sessão de usuário logado e não recebe requisição — não existe query, body nem visitante para ela usar. O estado entre execuções fica em arquivo no sandbox/ ou no banco.

Sem timers: o runtime é 100% síncrono. Nada de setTimeout, async ou await dentro de uma rotina; a pausa, quando precisa, é feita com sleep().

thread/lembrete-do-dia.js (trecho) — a rotina confere se já deu a hora antes de trabalhar

// fm = new FileManager();  dm = new DirectoryManager();

function devoRodarNoHorario(chave, hora, minuto) {
    var agora = new Date();
    if (agora.getHours() < hora) return false;
    if (agora.getHours() === hora && agora.getMinutes() < minuto) return false;

    var hoje = agora.getFullYear() + '-' + (agora.getMonth() + 1) + '-' + agora.getDate();
    var arquivo = '_estado/' + chave + '.json';
    if (fm.fileExists(arquivo)) {
        var st = JSON.parse(fm.readFile(arquivo));
        if (st.dia === hoje) return false;   // já rodou hoje
    }
    fm.writeFile(arquivo, JSON.stringify({ dia: hoje, em: agora.toISOString() }));
    return true;
}

if (devoRodarNoHorario('lembrete-do-dia', 8, 0)) {   // 1ª passada após as 08:00
    enviarLembretes();
}

O horário é “a partir de”, não “exatamente”. Com ciclo de 60 segundos, “08:00” acontece entre 08:00 e 08:01 — e, se o servidor estiver fora do ar nesse minuto, a rotina roda na volta. O relógio é o do servidor: new Date() usa o fuso dele, não o do seu cliente. E sem a checagem acima, uma rotina “diária” roda 1.440 vezes por dia.

Duas regras que evitam estrago: defina um teto de itens por rodada (uma rotina lenta atrasa o ciclo inteiro, inclusive dos outros sites do servidor) e marque o item como “em processamento” antes de agir, para que uma segunda passada não mande o mesmo e-mail duas vezes.

Como saber se rodou: o log é o único registro de uma rotina — ele fica em logger/thread/<domínio>/<script>/ e aparece na tela de Scripts. No painel, peça ⏱️ run_thread_once (“rode a rotina uma vez agora e me mostre o log”, ferramenta da lição 45) ou leia com 🪵 read_app_logs. Se um erro acontecer, ele vira uma linha no log — ninguém é avisado na hora. O campo Avisos (e-mail e/ou Telegram, “sempre” ou “só se der problema”) existe na automação, não na rotina.

Mecanismo 3 · pasta script/

Webhook: o endereço que outro sistema chama

Nos exemplos do guia, o webhook serve para o caso “o pagamento caiu” ou “pagamento do sinal aprovado”. Aqui não existe registro especial nem rota mágica: o arquivo em script/ é o endereço. O servidor tira o .js da URL — script/api.js responde em /api, e script/webhook-pagamento.js responde em /webhook-pagamento.

As quatro leis do webhook	O que isso significa na prática
1. Responda rápido, e responda 200	O provedor tem prazo curto — a documentação da plataforma cita cerca de 15s no Asaas, 10s no Pagar.me e 60s no Telegram. Se você demorar ou responder erro, ele reenvia, às vezes por dias. Receba, valide, guarde e responda: `{"received": true}`. Processamento pesado não entra aqui.
2. Toda entrega pode ser repetida	Reentrega é rotina: prazo estourado, repetição de rede, dois eventos para o mesmo fato. Guarde o id do evento e ignore o que já viu. Sem id no payload, o script compõe um — por exemplo `PAYMENT_CONFIRMED\|pay_123\|RECEIVED`. O que não pode é cobrar, avisar ou baixar estoque duas vezes pelo mesmo fato.
3. O payload é dica, não verdade	Qualquer um pode fazer um POST no seu endereço. Quando o efeito é dinheiro, estoque ou permissão, reconfira na API do provedor antes de agir: chegou “pagamento confirmado”, pergunte ao provedor qual é o status real. Se não bater, registre no log e não faça nada.
4. Trabalho pesado vai para a rotina	Enviar 300 e-mails, gerar PDF, chamar IA — nada disso cabe na janela do provedor. O webhook grava a tarefa numa fila no `sandbox/` e responde na hora; a rotina em `thread/` consome a fila no próximo ciclo.

O que responder em cada situação

Situação	Resposta	Por quê
Evento processado	200	Fim da linha.
Evento repetido (já visto)	200	É reentrega normal; não há nada a fazer.
Payload malformado ou token inválido	200 (e log)	Reenviar não vai consertar — o log serve para você investigar.
Falha temporária sua (banco fora do ar)	500	Aqui você quer a reentrega do evento.

script/webhook-pagamento.js (trecho) — o corpo do webhook termina respondendo

// 1) autenticação: token combinado com o provedor, comparado com o valor guardado no sandbox
// 2) idempotência: id do evento registrado antes de qualquer efeito
// 3) o fato é reconferido na API do provedor
// 4) o que é pesado vai para a fila:

fm.writeFile('webhook/fila/' + Date.now() + '_' + id + '.json', JSON.stringify(tarefa));

__PARAM.output = JSON.stringify({ received: true });
__PARAM.contentType = 'application/json';

Autenticação por token: o caminho comum é um cabeçalho com token fixo, comparado com o valor guardado no sandbox/. Token na query (?token=) também funciona, mas aparece em log de proxy — prefira o cabeçalho. O Telegram tem o segredo próprio (X-Telegram-Bot-Api-Secret-Token) e há validação pronta para Pix/QQPag.

Sem HMAC nativo: não existe validação de assinatura HMAC-SHA256 para o script. As saídas são tratar o caminho do webhook como segredo, reconferir o fato na API do provedor, ou usar um cabeçalho extra quando o provedor permitir. SHA-256 puro não é HMAC — nunca finge que valida, porque nunca vai bater.

Guarde o payload bruto: o corpo cru, gravado no sandbox/ com carimbo de data, é o que salva a depuração três semanas depois. Payload em www/ seria dado de cliente exposto na internet — nunca.

Toda decisão vai para o log: aceito, repetido, recusado por token, erro. Sem isso, um aviso que “não chegou” vira adivinhação.

Exemplo completo

Pagamento aprovado: webhook grava, rotina avisa

O caminho que a plataforma recomenda quando o efeito é dinheiro: o webhook faz o mínimo e responde rápido; quem trabalha de verdade é a rotina.

1. O gateway chama o siteO pagamento é confirmado e o provedor faz um POST em script/webhook-pagamento.js, ou seja, em /webhook-pagamento.

2. O webhook confereToken do cabeçalho batendo, id do evento registrado (idempotência), payload bruto gravado no sandbox/ e o status reconferido na API do provedor.

3. Enfileira e respondeA tarefa (“avisar o cliente”) vira um arquivo na fila do sandbox/ e o script responde {"received": true} em 200.

4. A rotina avisaNo próximo ciclo, a rotina em thread/ pega a fila, manda a mensagem (WhatsApp ou e-mail), marca o item como processado e escreve no log.

Por que não avisar direto no webhook? Porque o provedor desiste em poucos segundos e reenviaria o evento. E por que não fazer tudo na rotina, sem webhook? Porque sem o aviso de fora o site não fica sabendo que o pagamento caiu — a rotina teria de perguntar ao provedor de tempos em tempos. Cada peça faz a parte dela: o webhook escuta, a rotina executa.

Dúvidas

Perguntas frequentes

A automação de horário gasta tokens?

Sim. O campo Mensagem é enviado para a sessão escolhida e o Harness processa como se você tivesse digitado: cada disparo gasta tokens. Rotina e webhook rodam código, sem IA. O gasto aparece em 📊 Consumo de Tokens e o administrador pode definir um limite mensal por usuário em Usuários.

Dá para ser avisado quando a execução falha?

A automação tem o campo Avisos, com e-mail e/ou Telegram, no modo sempre (com a resposta) ou só se der problema — configure os canais antes em 🔔 Canais de aviso e confira com 📨 Enviar teste.

A rotina não tem esse campo: o registro dela é o log, em logger/thread/<domínio>/<script>/, que aparece na tela de Scripts e que o Harness lê com 🪵 read_app_logs ou mostra com ⏱️ run_thread_once.

Um webhook pode ser chamado duas vezes pelo mesmo fato?

Pode, e reentrega é rotina: prazo curto do provedor, repetição de rede ou dois eventos para o mesmo fato. O script guarda o id do evento e ignora o que já viu; sem id no payload, ele compõe um, como PAYMENT_CONFIRMED|pay_123|RECEIVED. E o valor que importa é sempre reconferido na API do provedor antes de qualquer efeito.

Preciso deixar o painel ou o navegador aberto?

Não. A rotina é um programa que o servidor roda sozinho, mais ou menos a cada minuto, e o webhook é um endereço do site que outro sistema chama. A automação fica marcada no painel e o Harness recebe a mensagem no horário configurado.

Posso validar a assinatura HMAC do provedor?

Não há HMAC nativo para o script. As saídas são: tratar o caminho do webhook como segredo, reconferir o fato na API do provedor antes de agir, ou usar um cabeçalho de token adicional quando o provedor permitir. SHA-256 puro não é HMAC e nunca bate com a assinatura.

Continue lendo

Automatizar é uma parte do app inteiro

Se o seu caso é ler dado de um sistema que já existe, ou colocar um agente de IA para atender os seus clientes, o caminho começa nas outras duas páginas.

Banco de dadosLigar o site ao MySQL, PostgreSQL, Supabase ou ao banco que roda na rede da sua empresa — com credencial cifrada e usuário só-leitura. Agentes por APIUsar os agentes de IA do site em outro sistema: chave no servidor, comandos como fp-agent-run e conversa por usuário. Guia do HarnessAs lições 13 (automações e avisos) e 45 (testar o que foi construído), com o exemplo completo da barbearia.

Contar minha ideia no WhatsApp Voltar à home