Webhook
Uma URL que qualquer sistema externo chama para disparar o agente, com o payload virando variáveis do processo.

O que é o webhook do processo
O webhook é o caminho mais direto para um sistema de fora acionar um agente: uma URL fixa que recebe um POST com JSON. Não exige credencial de conta nem chave de processo, porque o token embutido na própria URL é a credencial. É o que torna a integração viável com sistemas que só sabem fazer uma coisa: postar numa URL.
Origens: uma por sistema chamador
Um mesmo processo costuma ser chamado por mais de um sistema. Um BPO, por exemplo, pode ter o Salesforce de um cliente, o Oracle de outro e um sistema caseiro de um terceiro, todos disparando o mesmo agente e cada um mandando o JSON no seu próprio formato.
Para isso existem as origens. Cada origem tem:
- URLs próprias, uma de desenvolvimento e uma de produção
- Mapeamento próprio, porque cada sistema nomeia os campos do seu jeito
- Histórico de capturas próprio, para você testar uma origem sem misturar com as outras
Todas as origens convergem para as mesmas variáveis do processo. O agente é um só e não precisa saber quem o chamou: ele recebe as variáveis já preenchidas.
Quem identifica a origem é a própria URL. O sistema externo não precisa enviar nenhum campo extra para se apresentar, e cada execução de produção registra a origem na Trilha de Auditoria, o que permite acompanhar o volume por sistema chamador.
Crie uma origem por sistema, dê a ela o nome do sistema e entregue àquele time apenas a URL dele. O limite é de 10 origens por processo.
As duas URLs: DEV e PROD
| DEV | PROD | |
|---|---|---|
| O que faz ao receber | Captura o payload e mostra no modal. Nunca executa por conta própria. | Aplica o mapeamento salvo e dispara a versão publicada. |
| Quem dispara a execução | Você, clicando no botão de debug dentro do modal. | A própria chamada, automaticamente. |
| Qual versão roda | A versão em desenvolvimento, em modo Debug. | A versão publicada em produção. |
| Planos | Todos, inclusive o Free. | Segue a política de acesso à API externa. |

Capturar um payload de verdade
A forma correta de configurar um webhook é nunca escrever o JSON à mão. Peça ao sistema chamador que envie uma chamada real e trabalhe em cima do que ele mandou:
- Abra o modal de Webhook no Agent Builder. Enquanto ele estiver aberto, um indicador mostra que a origem está escutando.
- Copie a URL DEV da origem e entregue a quem vai chamar, ou dispare você mesmo um
POSTcom JSON de teste. - O payload aparece na lista de capturas imediatamente, sem precisar recarregar a página.
- Clique na captura para abrir a árvore do payload e seguir para o mapeamento.
Cada origem guarda as 10 capturas mais recentes. A partir daí, as antigas saem conforme as novas chegam. Você também pode apagar uma captura específica ou limpar a lista inteira, e isso nunca afeta o mapeamento salvo.
«•••» na captura, inclusive nas capturas que já existiam quando você salva o mapeamento. A URL de produção não guarda o corpo. Veja Dados Sensíveis.
Mapear o payload para as variáveis
O mapeamento é a ligação entre o JSON que chega e as variáveis do processo. O modal mostra duas colunas: o payload capturado à esquerda e as variáveis do processo à direita.

_headers.- Clique no campo desejado na árvore do payload, à esquerda.
- Clique na variável que deve recebê-lo, à direita.
- Repita para cada campo e clique em Salvar mapeamento.
Campo que carrega um segredo
Se um campo do payload traz um segredo (um token, uma senha, um CPF), mapeie-o para uma variável do tipo Secreto. Você a cria no modal Variáveis Globais do Fluxo - Matrix (ícone da Matrix), escolhendo o tipo Secreto, e depois a seleciona na coluna da direita como qualquer outra. Com isso:
- o valor não aparece em nenhum log da execução, e as etapas continuam recebendo o valor real em
{matrix.nome}; - enquanto a execução espera na fila, o valor fica cifrado;
- o campo aparece escondido nas capturas de teste da URL DEV.
Uma variável de outro tipo (Texto, por exemplo) não recebe nada disso: o valor aparece no log e fica guardado nas capturas. No ▶ Iniciar debug com esta captura, o valor de um parâmetro Secreto não é enviado (a tela avisa), porque esse caminho leva os valores pela URL. Veja Parâmetros de entrada: o tipo Secreto.
Com o mapeamento salvo, o botão ▶ Iniciar debug com esta captura roda o agente já com as variáveis preenchidas pelos valores daquela chamada. É a forma mais próxima do real de testar o fluxo antes de publicar.
Além dos campos simples
| O que dá para mapear | Como |
|---|---|
| Um nó inteiro | Use o botão ⊙ mapear nó ao lado de um grupo do payload. Numa variável do tipo Lista, mapeie um nó que é lista: cada elemento chega como um item, com o texto inteiro, e um nó objeto é recusado com 400 INVALID_MATRIX. Numa variável do tipo Objeto, chega como o objeto. Nos demais tipos, chega como o JSON completo daquele nó. |
| Parâmetros da URL | Aparecem na árvore sob _query. Útil quando o sistema chamador manda parte da informação na própria URL. |
| Cabeçalhos da chamada | Aparecem sob _headers, já sem os cabeçalhos sensíveis, que nunca são gravados. |
"1.234,90" numa Moeda vira o valor 1234,9, "sim" num Verdadeiro/Falso vira verdadeiro. Um valor que não cabe no tipo faz a chamada ser recusada com 400 INVALID_MATRIX, e a mensagem diz qual variável foi. O teste pelo ▶ debug com a captura confere do mesmo jeito. Detalhes: Como o tipo é aplicado.
400 INVALID_MATRIX; a simulação e o ▶ debug com a captura conferem do mesmo jeito. Uma variável de Opções sem valor padrão precisa estar mapeada. Numa variável de Formato, o valor do payload tem de estar no formato, com a mesma recusa; sem valor padrão, ela também precisa estar mapeada. Uma variável Obrigatório precisa estar mapeada e o payload tem de trazer um valor nela, Secreto incluso. Detalhes: Regra de uso.
400 INVALID_MATRIX.
Colocar em produção
Depois de validar no debug, entregue a URL PROD ao sistema chamador. A partir daí, cada chamada aplica o mesmo mapeamento e dispara a versão publicada, sem intervenção. O contrato da rota, com corpo, respostas e códigos de erro para quem vai escrever o lado que chama, está em Rotas de API.
Duas condições precisam estar satisfeitas para a URL de produção responder:
| Situação | O que acontece |
|---|---|
| O processo ainda não foi publicado | A URL de produção responde 409. Publique a versão para ativá-la (veja Versionamento). |
| O plano não inclui acesso à API externa | A URL de produção responde 402. O modal indica a partir de qual plano ela fica disponível. |
| O webhook está desligado | As URLs DEV e PROD respondem 403. Veja Ligar e desligar. |
Chamadas repetidas com o mesmo identificador de idempotência dentro de 24 horas não geram execuções duplicadas, o que protege contra o reenvio automático de sistemas que tentam de novo em caso de timeout.
WhatsApp, Instagram e Messenger (Meta)
A Meta confirma a URL antes de mandar mensagens: no painel do aplicativo, em WhatsApp → Configuração → Webhook, cole a URL (DEV para testar, PROD em produção) no campo URL de callback e escreva qualquer texto em Verificar token. A URL do processo responde à verificação sozinha. Depois, assine o campo messages.
Cada mensagem recebida chega como uma chamada ao webhook. Os caminhos mais usados no mapeamento:
| Caminho | O que é |
|---|---|
entry[0].changes[0].value.messages[0].from | Número de quem mandou |
entry[0].changes[0].value.messages[0].text.body | Texto da mensagem |
entry[0].changes[0].value.messages[0].id | Id da mensagem, para o Marcar como Lida e para responder citando a mensagem |
entry[0].changes[0].value.contacts[0].profile.name | Nome do perfil de quem mandou |
messages, e as variáveis mapeadas para ela ficam vazias: confira no início do processo se o texto ou o número vieram preenchidos antes de seguir.
Responder a conversa. Cada mensagem recebida é uma execução nova do processo. A resposta sai pelo conector WhatsApp Business, com o Número destino igual ao from e, para citar a mensagem, o Responder à mensagem igual ao id. Numa conversa de vários passos, o processo não fica esperando a próxima mensagem: guarde em que passo cada número está (num banco, pelo número) e leia esse estado no início de cada execução.
Responder ao sistema chamador
Por padrão, a URL de produção responde na hora: devolve o instanceID da execução e o agente continua o processamento. Serve quando o sistema chamador só precisa saber que o pedido foi aceito. Quando ele precisa do resultado na mesma chamada (um valor calculado, um número de protocolo, uma validação), a origem pode ficar em modo Aguardar: a conexão fica aberta até o processo responder.
Escolher o modo, por origem
No modal, logo abaixo das duas URLs, a linha RESPOSTA tem a escolha. Ela vale para a origem selecionada, então um sistema pode esperar o resultado enquanto outro continua recebendo a confirmação imediata. A mudança é salva na hora e vale só para a URL de produção: a URL DEV continua só capturando.
| Modo | O que o sistema chamador recebe | Quando usar |
|---|---|---|
| Imediata (padrão) | 200 com o instanceID, sem esperar o processo | Eventos que só precisam ser entregues, sem resposta de negócio |
| Aguardar | A resposta do processo, até o limite de espera escolhido (1 a 120 segundos, padrão 30) | Quem chama precisa do resultado na própria chamada |

Responder no meio do processo: o conector Webhook Response
Para decidir o que devolver, use o conector Webhook Response, na categoria Automação. Crie o conector uma vez, arraste-o para o ponto do processo em que a resposta já pode ser dada e preencha:

- Código HTTP: 200, 201, 202, 400, 401, 403, 404, 409, 422 ou 500. Vazio vale 200.
- Corpo: um JSON. Escreva
{{nome_da_variavel}}onde o valor deve entrar. Dentro de aspas o valor é inserido como texto seguro (aspas e quebras de linha são tratadas), e fora de aspas números, verdadeiro/falso e listas saem no formato certo. Quando o corpo é só{{nome_da_variavel}}e a variável guarda um texto em JSON (por exemplo, a resposta de outro conector), ele é enviado como JSON, e não como um texto com o JSON dentro.

{{retorno}}, então a resposta será o valor da variável retorno. O aviso amarelo lembra que este conector não tem Testar: confira pelo Debug.A resposta sai no momento em que o processo chega naquela etapa. O processo não para: as etapas seguintes continuam rodando normalmente depois que o chamador já recebeu a resposta. Se o processo passar por mais de uma etapa Webhook Response, vale a primeira.

O que sai quando não há conector
Com a origem em modo Aguardar e nenhuma etapa Webhook Response no caminho, a resposta sai ao fim do processo, com o mínimo necessário e nada além:
| Como o processo terminou | Código | Corpo |
|---|---|---|
| Concluiu, ou terminou dentro de um ramo sem próximo passo (nenhum erro envolvido) | 202 | { "instanceID": "...", "status": "FINALIZED" } |
Uma rota de encerramento (terminate) desenhada no processo foi tomada | 500 | { "instanceID": "...", "status": "TERMINATED" }. Esse caminho é ambíguo por natureza (pode ser um fim limpo desenhado de propósito, ou o jeito de quem desenhou abortar por um problema), então é tratado como falha |
| O processo estourou o limite de execução de etapas do agente (possível loop no desenho) | 500 | { "instanceID": "...", "status": "STEP_LIMIT_REACHED" } |
| Falhou ou foi parado | 500 | { "instanceID": "...", "status": "ERROR" }. O status também pode ser STOPPED (parado manualmente) ou CRASHED (o agente caiu) |
| O limite de espera acabou com o processo já em execução | 202 | { "instanceID": "...", "status": "running" } |
| O limite de espera acabou com o processo ainda esperando vaga na fila do runtime | 202 | { "instanceID": "...", "status": "queued" } |
Idempotency-Key: uma nova tentativa com a mesma chave devolve só o instanceID da execução original, sem o corpo da resposta.
Origem em modo Aguardar num runtime com fila
Com Enfileirar Jobs ligado no runtime, ou com um teto de execuções ao mesmo tempo no agente, a chamada do webhook entra na fila como qualquer execução e espera a vez. O limite de espera da origem conta desde a chegada da chamada, então o tempo na fila é descontado dele.
| A vaga chega | O que o sistema chamador recebe |
|---|---|
| Antes do limite de espera | A execução roda e a resposta sai como em qualquer chamada: a do conector Webhook Response, ou o status ao fim. |
| Depois do limite de espera | No instante em que o limite acaba, 202 com { "instanceID": "...", "status": "queued" }. A execução continua na fila e roda quando chegar a vez, mas a resposta dela não é entregue: o sistema chamador já foi respondido. |
O status do 202 diz onde a execução está quando o limite acaba: queued enquanto espera vaga, running depois de começar. O resultado se consulta por GET /v1/instances/:id, com as credenciais normais da API, que devolve queued, running e depois o status final. Detalhes da consulta: Rotas de API.
Uma execução cancelada pela opção Anular fila por exceção do runtime sai da fila sem rodar, e o sistema chamador que já recebeu o 202 queued não recebe outra resposta. Detalhes do teto e das regras da fila: Runtimes e Ambientes.
Como conferir antes de entregar a URL
No Debug ninguém está esperando, então o conector não envia nada: ele registra no log o código e o corpo que enviaria, já com as variáveis trocadas e os segredos do Cofre mascarados. É a forma de ver o JSON final e de descobrir uma variável sem valor ou um JSON com vírgula sobrando antes de a URL de produção entrar no ar. O mesmo registro aparece quando o conector roda numa execução que não tem chamador esperando, como um agendamento ou uma origem em modo Imediata.
Ligar e desligar
Todo agente nasce com o webhook ligado, e a origem Padrão é criada na primeira vez que o modal é aberto. A chave no canto direito do cabeçalho do modal liga e desliga o webhook do agente inteiro, todas as origens de uma vez.

| Ligado | Desligado | |
|---|---|---|
| Chamada na URL DEV | O payload é capturado no modal. | Responde 403 e nada é capturado. |
| Chamada na URL PROD | Dispara a versão publicada. | Responde 403 e nada é executado. |
| Publicar | Confere o mapeamento de cada origem contra a regra de uso das variáveis. | Não confere o webhook. |
| URLs, mapeamento e capturas | Guardados. | Continuam guardados e voltam a valer ao religar. |
Para capturar um payload e montar o mapeamento, o webhook precisa estar ligado.
Publicar com uma variável que exige valor
Uma variável da Matrix sem valor padrão, com uso Opções, Formato ou Obrigatório, precisa receber um valor em toda chamada. Com o webhook ligado, o Publicar confere cada origem que tem algum campo mapeado e recusa a publicação quando ela não envia essa variável, por exemplo: Não foi possível publicar. Webhook, origem "CRM": "data_referencia" não está mapeada e não tem valor padrão. Ajuste o mapeamento ou desligue o webhook.
Origem sem nenhum campo mapeado não entra na conferência. É o caso da origem Padrão criada quando o modal é aberto pela primeira vez: abrir o Webhook para ver como funciona não muda o Publicar. Uma chamada à URL de produção dessa origem é recusada com erro 400 enquanto a variável não tiver valor padrão nem mapeamento.
Quando o agente deixou de ser chamado por webhook:
- Abra o Webhook no editor.
- Clique na chave Ligado, no canto direito do cabeçalho, e confirme. Ela passa a mostrar Desligado.
- Publique.
Quando o agente é chamado por webhook, mapeie na origem o campo do payload que traz o valor e publique.
Rotacionar e excluir
- Rotacionar: gera uma URL nova para aquele ambiente daquela origem. A URL anterior para de funcionar na hora. Use quando a URL vazar ou quando um fornecedor deixar de ser autorizado.
- Excluir a origem: apaga as duas URLs dela imediatamente, junto com o mapeamento e as capturas. As demais origens continuam funcionando normalmente. Ao excluir a última, o modal cria uma origem Padrão nova, com URLs novas. Para parar de receber chamadas sem apagar nada, desligue o webhook.
Segurança e limites
| Item | Comportamento |
|---|---|
| Credencial | O token da URL é a única credencial. Trate a URL como uma senha: quem a tem consegue disparar o processo. |
| Headers sensíveis | Authorization, Cookie e a chave de processo nunca são gravados na captura. Segredo de quem chama não fica em repouso. |
| Dados sensíveis | A URL DEV guarda o corpo recebido (10 capturas por origem), então use dados de teste nela. Campo mapeado para um parâmetro Secreto é escondido na captura e cifrado na fila de execução. A URL PROD não guarda o corpo. Veja Dados Sensíveis. |
| Tamanho do corpo | A chamada aceita até 1 MB. Acima de 100 KB, a captura entra marcada como truncada e não fica disponível para mapear no modal. |
| Codificação do corpo | O padrão é UTF-8. O webhook também aceita ISO-8859-1 (latin1), comum em ERPs e integrações mais antigas, desde que o sistema chamador declare no cabeçalho: Content-Type: application/json; charset=ISO-8859-1. Outra codificação é recusada com 415. Se o cabeçalho declarar ISO-8859-1 mas os bytes forem UTF-8 válido, o corpo é lido como UTF-8, para o acento não chegar trocado. |
| Tamanho da resposta | No modo Aguardar, o corpo devolvido ao chamador pode ter até 256 KB. Acima disso o conector não envia e avisa no log. |
| Limite de espera | De 1 a 120 segundos (padrão 30), contado desde a chegada da chamada. Se acabar antes da resposta, o sistema chamador recebe 202 com running (o processo já rodava) ou queued (ainda esperava vaga na fila do runtime), e a execução segue. |
| Esperas simultâneas | Até 50 chamadas aguardando ao mesmo tempo por processo. Acima disso, a chamada seguinte é tratada como no modo Imediata (200 com o instanceID), sem erro. |
| Origens por processo | Máximo de 10. |
| Capturas por origem | 10, em lista circular. |
| Permissão | Criar origens, mapear e rotacionar exigem permissão de edit no processo. |
Boas práticas
- Uma origem por sistema, com o nome do sistema. Seis meses depois, "Salesforce ACME" diz muito mais do que "Origem 2", e rotacionar a URL de um cliente não afeta os outros.
- Sempre configure a partir de uma captura real. O JSON que você imagina raramente é o JSON que o sistema manda.
- Rode o debug com a captura antes de entregar a URL de produção. É o teste que usa dados verdadeiros no fluxo verdadeiro.
- Crie as variáveis da Matrix antes de mapear. Sem elas, a coluna da direita não tem para onde apontar.
- Use dados de teste na URL DEV e mapeie o que é segredo para um parâmetro Secreto. É o que impede o segredo de ficar guardado na captura e de aparecer nos logs. Veja Dados Sensíveis.
- Teste na Sandbox quando não quiser ocupar um runtime. A captura e o debug com o payload recebido funcionam igual.
- Trate a URL como credencial. Não coloque em repositório, ticket público ou grupo de mensagens.
- Rotacione ao trocar de fornecedor. É mais rápido e mais seguro do que auditar quem ainda tem a URL antiga.
