Webhook

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

Nesta página

O que é o webhook do processo
Origens: uma por sistema chamador
As duas URLs: DEV e PROD
Capturar um payload de verdade
Mapear o payload para as variáveis
Colocar em produção
Responder ao sistema chamador
Rotacionar e excluir
Segurança e limites
Boas práticas

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.

Webhook, Chaves de API e Agendamento As três formas disparam o mesmo agente, mas resolvem problemas diferentes. O Webhook serve quando quem chama é um sistema de terceiros que você não controla. As Chaves de API servem quando você escreve o código que chama e quer autenticação explícita. O Agendamento serve quando ninguém chama e o gatilho é o relógio.

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.

Um mapeamento por origem, não por chamada O mapeamento que você salva vale para todas as chamadas daquela origem, não só para a captura que está na tela. Você configura uma vez, quando integra o sistema, e ele passa a valer dali em diante.

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.

Modal de webhook com as URLs DEV e PROD — O modal, com a origem selecionada e o par de URLs. Ao lado de cada uma, os botões de copiar e de gerar uma nova. O aviso em amarelo lembra que a URL de produção só responde depois que a versão for publicada.

Por que a URL de desenvolvimento não executa sozinha Enquanto você está integrando, um sistema externo mal configurado pode disparar dezenas de chamadas. Se cada uma iniciasse uma execução, você gastaria crédito e tempo em execuções que nem queria ver. A URL DEV existe para escutar: ela guarda o que chegou e espera você decidir o que rodar.

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 POST com 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.

Envie dados de teste à URL DEV A captura guarda o corpo que a chamada trouxe, para você poder mapear. Por isso a URL DEV deve receber dados de teste, não dados reais. A exceção é o campo que o mapeamento já aponta para um parâmetro do tipo Secreto: o valor dele é trocado por «•••» 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.

Payload capturado à esquerda e variáveis do processo à direita — Com uma captura recebida: o payload à esquerda, já navegável, e as variáveis do processo à direita. O botão **mapear nó** aparece em cada grupo, e os cabeçalhos da chamada ficam sob `_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.

Sem variáveis não há mapeamento A coluna da direita lista as variáveis já cadastradas na Matrix do processo. Se ela estiver vazia, crie as variáveis primeiro, pelo ícone de Matrix no cabeçalho do builder. Elas passam a aparecer aqui na hora.

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.

O valor é lido pelo tipo da variável Cada campo mapeado é convertido pelo tipo da variável que o recebe: "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.

Renomear a variável não quebra o mapeamento O vínculo é feito com o identificador interno do campo, e não com o nome que você vê. Renomear a variável na Matrix mantém o mapeamento intacto.

Variável sem mapeamento usa o valor padrão Se uma variável da Matrix não recebe nenhum campo do payload, o processo roda com o valor padrão cadastrado nela. Não é erro, e é o que permite mapear só o que aquele sistema realmente envia.

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 mapeamento de produção é aplicado no servidor A chamada de produção não depende de nenhuma tela aberta. O mapeamento salvo é lido e aplicado no servidor, e a execução segue exatamente o mesmo caminho de um disparo por API, inclusive na checagem de créditos.

Mapeamento novo só vale em produção depois de publicar Campos que você mapear na versão em desenvolvimento continuam sem efeito nas chamadas de produção até a versão ser publicada. Se um sistema já em produção passou a enviar um campo novo, mapeie, teste no debug e publique.

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.

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

Modal de webhook com a linha RESPOSTA em modo Aguardar — A linha **RESPOSTA** do modal, logo abaixo das URLs DEV e PROD, com o modo **Aguardar** e o limite de espera. O texto embaixo resume o que o sistema chamador vai receber.

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:

Painel de conectores com a busca por Webhook Response — O conector **Webhook Response** no painel de conectores, encontrado pela busca. É o ícone verde com a seta de retorno.

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.

Configuração do conector Webhook Response com código HTTP e corpo da resposta — A configuração do conector: o **Código HTTP** e o **Corpo da resposta**. Aqui o corpo é só `{{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.

Fluxo com a etapa Webhook Resposta antes do fim do processo — No fluxo, a etapa que responde ao chamador é uma etapa de conector como as outras (aqui, **Web Hook Resposta**, a última antes do fim). Colocá-la mais cedo faz o chamador receber a resposta antes de o processo terminar.

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 ambiente	202	`{ "instanceID": "...", "status": "queued" }`

Variáveis e mensagens de erro nunca saem sozinhas A resposta padrão não leva variável do processo nem a mensagem de erro, que pode conter endereços e trechos internos. O que o sistema chamador recebe além do status é sempre uma escolha sua, feita no conector Webhook Response.

Passou do limite de espera? Não reenvie a chamada O 202 quer dizer que o processo foi aceito e segue, em execução ou esperando vaga na fila do ambiente. Reenviar a mesma chamada cria outra execução e consome outro crédito. Se o sistema chamador retenta sozinho em caso de demora, configure um limite maior que o dele ou envie o cabeçalho 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 ambiente com fila

Com Enfileirar Jobs ligado no ambiente, 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 ambiente 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: Ambientes Runtime.

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.

Depende de o runtime estar atualizado A resposta é enviada pelo runtime instalado no ambiente. Num runtime de versão anterior a este recurso, o modo Aguardar continua aceito, mas o sistema chamador só recebe o 202 quando o limite de espera acaba, e uma etapa Webhook Response falha por não reconhecer o conector. Atualize o runtime do ambiente antes de ligar o modo em produção.

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.

Rotacionar quebra a integração até o outro lado atualizar Não existe período de convivência entre a URL velha e a nova. Combine a troca com quem chama antes de rotacionar a URL de produção.

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.
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 ambiente), 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.

Em somente leitura o modal é só consulta Sem uma versão em desenvolvimento aberta, o modal abre para conferir URLs e mapeamentos, mas nada pode ser alterado e ele não fica escutando capturas. Veja Versionamento → O editor em somente leitura.

Mapeamento não salvo segura a publicação Se você deixar um mapeamento em aberto, ele vira uma pendência e o botão de publicar não aparece até que você salve.

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

← Anterior Rotas de API Próximo → Créditos