Webhook de entrada e integração com formulários

Use webhook de entrada quando um sistema externo precisa enviar dados para a Agilize e transformar esse evento em ação operacional. O caso mais comum é receber cadastros de formulários, landing pages, ERPs, parceiros, sistemas próprios ou automações no-code para criar ou atualizar oportunidades, contatos, empresas, tarefas e campos do CRM.

O webhook de entrada fica em https://my.agilize.app/integration/webhook.

Acesso pela tela: Central de Configurações > Integrações > Webhook.

Quando usar

Use webhook de entrada para:

• capturar leads de formulários de site ou landing page;
• receber cadastros enviados por parceiro, ERP, sistema acadêmico, e-commerce ou ferramenta interna;
• criar ou atualizar contato, empresa ou oportunidade no CRM;
• preencher origem, funil, etapa, responsável, tags, telefone, e-mail e campos adicionais;
• criar tarefa ou atividade a partir de uma solicitação recebida;
• mapear o responsável a partir de e-mail, unidade, loja, campanha ou outra chave enviada no payload;
• separar caminhos do fluxo conforme um valor recebido, como produto, cidade, formulário, unidade, origem ou tipo de evento.

Não use webhook de entrada quando a integração precisa consultar muitos dados da Agilize. Nesse caso, use a API. Também não use JavaScript público da página para chamar a URL tokenizada diretamente; prefira envio pelo servidor do site, plugin de formulário ou endpoint intermediário.

Fluxos que podem ser processados

O fluxo visual de webhook pode combinar estes caminhos:

Para detalhes de cada node disponível no builder, consulte Nodes de webhooks.

Antes de configurar

Prepare estas informações antes de criar o webhook:

• qual sistema vai enviar o evento;
• quais campos chegam no payload;
• qual entidade deve ser criada ou atualizada: oportunidade, contato ou empresa;
• qual campo será usado para deduplicação, normalmente telefone ou e-mail;
• qual funil, etapa e origem serão usados quando o fluxo criar oportunidade;
• quais tags e campos adicionais precisam ser preenchidos;
• quem será o responsável: usuário fixo, usuário mapeado, equipe ou nenhum responsável;
• como o sistema de origem vai registrar erro ou tentativa de envio.

Se o formulário não envia JSON com controle suficiente de campos e cabeçalhos, crie uma ponte no servidor do site para receber o formulário, validar os dados e enviar o JSON final para a Agilize.

Como configurar na Agilize

1. Acesse https://my.agilize.app/integration/webhook.
2. Clique para criar um novo webhook.
3. Informe um nome claro, como Landing page - orçamento B2B.
4. Salve o webhook para gerar a URL de entrada.
5. No builder visual, mantenha o node Início do Fluxo como primeiro passo.
6. Adicione Debug / Inspeção de Evento logo após o início durante a configuração.
7. Ative a escuta do próximo evento no node de debug.
8. Envie um payload real de teste a partir do sistema externo.
9. Revise o payload capturado e ajuste os mapeamentos.
10. Adicione os nodes necessários, como Gerar Entidade, Mapear Usuário, Fluxos por Valor, Criar Tarefa/Atividade, Alterar Campo Adicional ou Alterar Etapa do Lead.
11. Teste novamente com payloads representando os principais cenários.
12. Remova testes desnecessários e mantenha logs suficientes para investigação.

Depois de salvar, a URL exibida segue este formato:

https://api.agilize.app/integration/webhook/incoming/{token}/{webhookId}

O token é gerado automaticamente pela Agilize. Não crie, edite ou publique esse token manualmente.

Como enviar a requisição HTTP

A requisição deve ser um POST com corpo JSON.

POST /integration/webhook/incoming/{token}/{webhookId} HTTP/1.1
Host: api.agilize.app
Content-Type: application/json
Accept: text/plain

Exemplo em cURL:

curl -X POST "https://api.agilize.app/integration/webhook/incoming/{token}/{webhookId}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/plain" \
  --data '{
    "event": "lead.created",
    "externalId": "site-12345",
    "submittedAt": "2026-08-03T14:30:00-03:00",
    "form": {
      "id": "lp-b2b",
      "name": "Landing page B2B"
    },
    "lead": {
      "name": "Maria Souza",
      "phone": "+5511999999999",
      "email": "maria@example.com"
    },
    "company": {
      "name": "Empresa Exemplo",
      "document": "00000000000000"
    },
    "utm": {
      "source": "google",
      "medium": "cpc",
      "campaign": "captacao-b2b",
      "content": "anuncio-1"
    }
  }'

Resposta esperada:

ACCEPT

Essa resposta confirma que a Agilize recebeu a requisição para processamento. O processamento do fluxo acontece de forma assíncrona; por isso, um ACCEPT não significa que a oportunidade já foi criada. Valide o resultado no debug, nos logs e no CRM.

Headers e formato

Use estes cabeçalhos como padrão:

A Agilize processa o corpo JSON recebido. Não dependa de cabeçalhos customizados para campos que precisam ser usados no fluxo visual, porque o mapeamento operacional deve partir do payload. Se precisar registrar source, formId, assinatura, versão do formulário ou identificador de evento, envie esses valores dentro do JSON.

Evite multipart/form-data e application/x-www-form-urlencoded para esse endpoint. Se o plugin de formulário só envia formulário tradicional, use uma ponte no servidor para converter os dados em JSON.

Estrutura recomendada do payload

Não existe um payload único obrigatório para todos os casos. O importante é manter nomes estáveis e enviar campos suficientes para deduplicar, atribuir e auditar o registro.

{
  "event": "lead.created",
  "externalId": "id-unico-do-sistema-origem",
  "submittedAt": "2026-08-03T14:30:00-03:00",
  "source": "site",
  "form": {
    "id": "formulario-orcamento",
    "name": "Formulário de orçamento"
  },
  "lead": {
    "name": "Nome do lead",
    "phone": "+5511999999999",
    "email": "lead@example.com",
    "message": "Mensagem enviada no formulário"
  },
  "company": {
    "name": "Nome da empresa",
    "document": "00000000000000"
  },
  "utm": {
    "source": "google",
    "medium": "cpc",
    "campaign": "campanha",
    "content": "criativo",
    "term": "palavra-chave"
  }
}

No builder, use variáveis do payload para preencher campos dos nodes. Exemplos:

Integração com Elementor

O Elementor Pro permite adicionar ações após o envio do formulário e inclui a opção de webhook para compartilhar informações enviadas pelo visitante com outros sistemas. Veja a referência do Elementor em Actions After Submit e a documentação técnica de Elementor Forms.

Caminho recomendado:

1. No Elementor, abra o formulário.
2. Em Actions After Submit, adicione Webhook.
3. Cole a URL gerada pela Agilize.
4. Envie um teste e confira o node Debug / Inspeção de Evento.
5. Se o payload não chegar como JSON utilizável, troque para uma ponte no servidor WordPress ou em uma função serverless.

Para produção, prefira esta arquitetura:

Elementor Form -> WordPress/backend do site -> validação e normalização -> Agilize webhook

Essa ponte permite validar spam, normalizar telefone, incluir UTMs, gravar log local e impedir que o token do webhook seja usado diretamente por scripts públicos.

Plugins de formulário mais comuns

Se o plugin não permitir escolher Content-Type: application/json ou montar um JSON estável, não force a integração direta. Crie um endpoint no servidor do site para receber o formato do plugin e reenviar para a Agilize no padrão correto.

Ponte server-side recomendada

A ponte server-side é um pequeno endpoint no servidor do site, WordPress, middleware, serverless function ou backend próprio. Ela recebe o formulário, valida e só então envia para a Agilize.

Use essa ponte quando:

• o formulário é público e recebe spam;
• o plugin não controla bem o formato do JSON;
• você precisa validar assinatura, captcha, origem, domínio ou nonce;
• precisa normalizar telefone, e-mail, documento ou UTM antes de criar o lead;
• quer registrar tentativas, erros e reenvios fora da Agilize;
• não quer deixar a URL tokenizada configurada em vários plugins ou páginas.

Exemplo em Node.js:

app.post('/formulario/orcamento', async (req, res) => {
  const body = req.body
  if (!body.email && !body.phone) {
    return res.status(400).json({ ok: false, message: 'Informe e-mail ou telefone.' })
  }
  const payload = {
    event: 'lead.created',
    externalId: body.id || body.submissionId,
    source: 'site',
    submittedAt: new Date().toISOString(),
    form: {
      id: 'orcamento',
      name: 'Formulário de orçamento'
    },
    lead: {
      name: body.name,
      phone: body.phone,
      email: body.email,
      message: body.message
    },
    utm: body.utm || {}
  }
  const response = await fetch(process.env.AGILIZE_WEBHOOK_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'text/plain'
    },
    body: JSON.stringify(payload)
  })
  if (!response.ok) {
    return res.status(502).json({ ok: false, message: 'Falha ao enviar para a Agilize.' })
  }
  return res.json({ ok: true })
})

No exemplo, AGILIZE_WEBHOOK_URL deve ficar em variável de ambiente no servidor. Não grave essa URL em JavaScript público, HTML, repositório aberto ou prints.

Regras de segurança

• Envie para a Agilize a partir do servidor sempre que possível.
• Não exponha a URL com token em scripts públicos, páginas HTML, tags de analytics ou documentação aberta.
• Não envie chaves de API, senhas, tokens de terceiros ou segredos dentro do payload.
• Valide captcha, domínio de origem e campos obrigatórios antes de chamar a Agilize.
• Normalize telefone e e-mail antes da deduplicação.
• Registre externalId, form.id, event e submittedAt para facilitar auditoria.
• Use deduplicação por telefone ou e-mail no node Gerar Entidade.
• Evite payloads grandes, arquivos anexos e dados sensíveis desnecessários.
• Se o formulário recebe anexos, envie links controlados ou trate o arquivo em uma integração própria antes de acionar o webhook.
• Limite quem pode editar webhooks, porque alterar fluxo, token ou mapeamento pode criar dados incorretos no CRM.
• Se suspeitar que a URL vazou, crie um novo webhook, atualize o sistema de origem e desative o fluxo antigo.

Como testar

1. Crie o webhook em ambiente controlado.
2. Adicione o node Debug / Inspeção de Evento logo após o início.
3. Ative a escuta do próximo evento.
4. Envie um payload real do formulário ou use cURL.
5. Confirme se payload aparece com os campos esperados.
6. Configure Gerar Entidade com nome, telefone, e-mail, funil, etapa, origem e deduplicação.
7. Envie novo teste.
8. Confira se o contato, empresa ou oportunidade foi criado no CRM.
9. Teste duplicidade usando o mesmo telefone ou e-mail.
10. Teste cenários incompletos, como telefone ausente, e-mail inválido ou formulário sem UTM.

Troubleshooting

Próximos passos

• Consulte Nodes de webhooks para montar o fluxo visual.
• Consulte Rastreamento de UTM em leads e conversas WhatsApp para preservar dados de campanha.
• Consulte Automações de CRM quando o lead criado por webhook precisar iniciar cadências, tarefas ou movimentações posteriores.