#Como iniciar uma automação a partir de um sistema externo (webhook)?

Use o gatilho Webhook recebido (categoria Webhooks): a automação ganha uma URL única e passa a iniciar sempre que qualquer sistema — um formulário próprio, um ERP, um Zapier/Make, um script — enviar um POST com JSON para essa URL. Não depende de integração nativa com a plataforma de origem.

Papel: qualquer membro com acesso ao workspace.

#Passo a passo

1. No canvas da automação, adicione (ou troque) o gatilho e escolha Webhook recebido, na categoria Webhooks.
2. O painel de configuração abre já com a URL do webhook criada para esta automação. Clique em Copiar e cole no seu sistema externo.
3. Antes de ativar, use Testar payload: cole um JSON de exemplo e clique em Testar. Você vê como ele seria interpretado — qual contato seria usado (ou criado) e quais variáveis ficariam disponíveis — sem gravar nada e sem iniciar a automação.
4. Clique em Salvar e ative a automação.
5. Envie um POST real e confira em Últimas chamadas recebidas (no mesmo painel) se ela chegou e com qual resultado.

#O que enviar no corpo do POST

O corpo precisa ser um objeto JSON e identificar o contato de pelo menos uma destas formas:

• email e/ou telephone — a plataforma procura um contato existente (deduplicação por e-mail e telefone). Se não encontrar, cria o contato.
• leadId — usa exatamente esse contato, sem criar nada.

Além da identificação, o payload aceita:

• Campos do contato: name, document, instagram, birthday (AAAA-MM-DD), profession, city, state, address — preenchem o contato novo, ou completam campos vazios do contato existente (nunca sobrescrevem o que já está preenchido).
• customFields: objeto com campos customizados do contato, referenciados por nome (ex.: { "customFields": { "Plano": "Pro" } }).
• tags: lista de até 20 nomes de tags para aplicar ao contato (tags que ainda não existem são criadas).
• kind: reservado. Hoje só aceita "lead" (pode ser omitido); qualquer outro valor faz a chamada ser recusada.
• Qualquer outra chave vira variável da execução: um payload com "origem": "meu-erp" deixa {{origem}} disponível nas mensagens, requisições HTTP e condições dos passos seguintes. Até 100 chaves por chamada, com nomes de até 128 caracteres.

Algumas chaves são reservadas pela automação (leadId, ownerId, flowId, cardId, offerId, tags, customFields, entre outras de uso interno) e não viram variável. Se o seu sistema usa um desses nomes, renomeie o campo — a ferramenta Testar payload lista tudo o que foi ignorado.

Exemplo:

{
  "email": "contato@exemplo.com",
  "name": "Maria Souza",
  "customFields": { "Plano": "Pro" },
  "tags": ["webhook"],
  "origem": "meu-erp",
  "valorCarrinho": 149.9
}

#Respostas

#Segurança, limites e repetições

• A URL é o segredo. Trate-a como uma senha. Se ela vazar, clique em Rotacionar URL no painel do gatilho: uma nova URL é gerada na hora e a antiga passa a responder erro — sem precisar recriar a automação.
• Limites: o corpo aceita até 32 KB, e cada origem pode enviar até 300 chamadas por minuto.
• Chamadas repetidas: envie o cabeçalho X-Idempotency-Key (ou o campo idempotencyKey no corpo) com um identificador seu. Reenvios com a mesma chave dentro de 24 horas contam como uma chamada só — a automação não inicia duas vezes. Se a chamada falhar, a chave é liberada: reenviar depois de corrigir funciona normalmente.
• Mesmo sem chave de idempotência, a automação respeita o intervalo mínimo entre execuções para o mesmo contato configurado nela (padrão de 1 hora).

#Depurando uma integração

O painel do gatilho mostra as últimas chamadas recebidas, com o payload enviado e o resultado:

A lista não atualiza sozinha — clique em Atualizar depois de enviar o POST.

Para conferir o que cada chave do payload virou dentro da automação, abra a execução na aba Execuções e veja os dados e as variáveis daquela execução.

Se a chamada aparece como Aceita mas a automação não roda, confira:

• se a automação está ativa — em automação pausada ou em rascunho o contato é criado normalmente e a chamada é registrada, mas nenhuma execução inicia;
• se o mesmo contato já iniciou esta automação dentro do intervalo mínimo configurado nela (padrão de 1 hora).

Um detalhe do email: ele é comparado exatamente como enviado. Se o seu sistema manda Maria@Exemplo.com e o contato foi cadastrado como maria@exemplo.com, serão dois contatos diferentes — padronize a caixa no seu lado.