Webhooks
Nível de acesso requerido
Admin ou Super Admin
Para que servem os Webhooks?
Webhooks permitem que o Flowi Agentic notifique sistemas externos automaticamente quando eventos ocorrem na plataforma, sem que o sistema externo precise ficar consultando (polling).
Exemplos de uso:
- Notificar um ERP quando uma instância de compra é aprovada
- Enviar dados para um dashboard externo quando uma tarefa é concluída
- Disparar automação em outro sistema quando um processo termina
Como funcionam
Quando um evento ocorre no Flowi Agentic, o sistema envia uma requisição HTTP POST para a URL cadastrada no webhook, com os dados do evento no corpo (JSON).
Cadastrando um webhook
- Acesse Integração → Webhooks
- Clique em Novo Webhook
- Preencha:
- Nome — identificação do webhook
- URL — endpoint do sistema externo que vai receber as notificações
- Eventos — quais tipos de evento disparam esse webhook
- Secret — chave secreta para validação HMAC (opcional de informar — a plataforma gera um se você não informar)
- Clique em Salvar
Para onde o webhook pode enviar
Cada tenant declara os destinos permitidos dos seus webhooks, em Integração → Webhooks → Destinos permitidos — um host por linha:
erp.cliente.com.br
*.parceiro.com.br*.parceiro.com.br alcança api.parceiro.com.br e não alcança parceiro.com.br. A porta é ignorada na comparação. É o mesmo formato da lista de destinos dos Agentes de IA — as duas metades do mesmo controle.
Por que isso existe: antes disso, o webhook mandava os eventos de processo do tenant para qualquer URL que um administrador tivesse digitado, e nada respondia "se este webhook disparar, para onde vão os dados" antes de ele disparar. A lista responde, e a tela mostra, para cada webhook, o host efetivo e o estado dele:
| Estado | O que significa |
|---|---|
| Destino declarado | o host está na lista — vai entregar |
| Sem lista declarada | nada limita o destino; a instalação permite, mas ninguém declarou nada |
| Fora da lista de destinos | o host não está na lista — não vai entregar |
| Nenhum destino declarado | a instalação exige lista e este tenant não tem nenhuma |
Um destino que não está na lista é recusado ao salvar, com o host no texto do erro. Se a lista mudar depois que o webhook foi cadastrado, a entrega é recusada no momento do envio e fica registrada como BLOCKED no histórico, com o motivo — não é uma falha de rede, e não é retentada.
O estado da lista é calculado a partir do host escrito na URL, e só dele. A verificação de que o endereço não é interno acontece em dois outros momentos — ao salvar o webhook e a cada envio — e não aparece nesse estado: um host que passou a resolver para um endereço interno depois do cadastro continua exibido como Destino declarado e é recusado na hora de entregar.
Endereço interno nunca é destino
localhost, 127.0.0.1, as faixas privadas (10., 172.16-31., 192.168.), link-local e os endpoints de metadados de nuvem (169.254.169.254) são recusados mesmo que você os escreva na lista. A lista amplia o alcance externo; ela não revoga essa proteção.
Instalação nova: WEBHOOKS_EGRESS_DEFAULT_POLICY=deny
Com allow (padrão, por compatibilidade), tenant sem lista entrega para qualquer endereço externo. Com deny, tenant sem lista não entrega nada, e quem integra declara onde. Gêmeo de AI_HTTP_TOOL_DEFAULT_POLICY.
O que aconteceu com os webhooks que já existiam
A atualização preencheu a lista de cada tenant com os hosts dos webhooks que ele já tinha. Nada que entregava parou de entregar, e a lista nasceu verdadeira: é o conjunto de destinos que estavam realmente em uso. Cadastrar um destino novo passou a ser dois passos — declarar o host e depois cadastrar o webhook.
Validação HMAC
Se você configurar um secret, o Flowi Agentic assina cada payload com HMAC-SHA256 e inclui a assinatura no header:
X-FlowIa-Signature: sha256=<assinatura>No sistema receptor, valide a assinatura usando o mesmo secret: ela prova que o corpo saiu daqui e não foi alterado no caminho.
O que a assinatura não diz é quando a requisição foi feita. Não há carimbo de tempo nem número de sequência no cabeçalho, e a retentativa reenvia o mesmo corpo com a mesma assinatura — o mesmo evento pode chegar até três vezes, todas válidas. Trate cada entrega como idempotente, usando os dados do próprio evento para reconhecer o que já foi processado.
Eventos disponíveis
| Evento | Disparado quando |
|---|---|
instance.started | Uma instância de processo é iniciada |
instance.completed | Uma instância é concluída |
instance.failed | Uma instância falha |
task.created | Uma nova tarefa é criada |
task.completed | Uma tarefa é concluída |
task.overdue | Não implementado — veja o aviso abaixo |
task.overdue não é disparado
Vencimento de prazo não é um evento do motor: nada acontece no instante em que a data passa. Entregar esse evento exige uma varredura periódica das tarefas abertas, que a plataforma não faz. Se você cadastrar um webhook só para ele, não receberá nada.
Quando a entrega acontece
O evento grava a entrega como pendente, e um processo em segundo plano a envia — em até um minuto, não no instante do evento. A chamada ao seu servidor fica de propósito fora da transação do processo: se ela acontecesse ali dentro, uma instância concluindo seguraria recursos do banco durante todo o tempo de resposta do seu endpoint, inclusive o timeout.
E se o processo desfizer a transação, a entrega desfaz junto. Uma instância que não chegou a iniciar não anuncia que iniciou.
Retentativa
Em caso de falha (servidor externo retornar erro ou não responder), o Flowi Agentic reenfileira a entrega e tenta de novo a cada minuto, até três tentativas. Depois disso a entrega fica como FAILED e não é mais tentada. O histórico fica registrado em cada webhook.
Não há backoff exponencial — o intervalo é fixo.
Monitorando entregas
Na listagem de webhooks, clique em um para ver as 50 entregas mais recentes daquele webhook: o evento, o status (SUCCESS, PENDING, RETRYING, FAILED, BLOCKED), o código HTTP devolvido pelo seu servidor, o número de tentativas e a data. O corpo enviado não é exibido nessa tela.