# Agilize Docs para IA - Página atual Este arquivo contém uma versão focada e legível por IA da página aberta na documentação pública da Agilize. Use esta versão quando a pergunta do usuário estiver restrita ao documento atual. Última geração: 2026-08-03T18:39:32.580Z ## Página - Título: Webhook de entrada e integração com formulários - URL humana: https://agilize.app/docs/configuracao/canais-whatsapp-integracoes/webhook-de-entrada-formularios - Leitura completa para IA: https://agilize.app/docs/llms.txt - Descrição: Como receber eventos externos na Agilize por webhook de entrada, configurar fluxos, enviar requisições HTTP em JSON e integrar formulários como Elementor, Gravity Forms, WPForms e Contact Form 7. ## Seções - Quando usar - Fluxos que podem ser processados - Antes de configurar - Como configurar na Agilize - Como enviar a requisição HTTP - Headers e formato - Estrutura recomendada do payload - Integração com Elementor ## Conteúdo da página # 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](https://my.agilize.app/integration/webhook). Acesso pela tela: Central de Configurações > Integrações > Webhook. --- title: "Caminho do webhook de entrada" caption: "O sistema externo envia JSON para a URL tokenizada; o fluxo visual interpreta o payload e executa ações na Agilize." definition: | flowchart LR A[Formulário ou sistema externo] --> B[POST JSON] B --> C[Webhook de entrada] C --> D[Debug e mapeamento] D --> E{Fluxo visual} E --> F[Criar oportunidade] E --> G[Criar contato ou empresa] E --> H[Criar tarefa] E --> I[Atualizar campos e etapa] --- ## 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: | Fluxo | Como funciona | | --- | --- | | Captura de lead com deduplicação | Recebe dados de formulário, usa telefone ou e-mail para evitar duplicidade e cria ou reaproveita uma oportunidade. | | Contato e empresa a partir de sistema externo | Recebe dados de cadastro, cria ou reaproveita empresa e contato, e salva valores relevantes em campos adicionais. | | Distribuição por responsável ou equipe | Mapeia um usuário por e-mail ou tabela de de/para, ou distribui para uma equipe configurada. | | Criação de tarefa | Cria atividade no CRM depois que a entidade principal foi localizada ou criada. | | Atualização de etapa ou campo adicional | Altera etapa da oportunidade ou preenche campos adicionais usando dados do payload. | | Roteamento por valor | Direciona o fluxo conforme campos como `event`, `source`, `formId`, `product`, `city` ou `utm.source`. | Para detalhes de cada node disponível no builder, consulte [Nodes de webhooks](/docs/configuracao/referencias/nodes-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](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: ```text 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. ```http POST /integration/webhook/incoming/{token}/{webhookId} HTTP/1.1 Host: api.agilize.app Content-Type: application/json Accept: text/plain ``` Exemplo em cURL: ```bash 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: ```text 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: | Header | Valor recomendado | Observação | | --- | --- | --- | | `Content-Type` | `application/json` | Obrigatório para o corpo ser interpretado como JSON. | | `Accept` | `text/plain` | A resposta de sucesso é texto simples: `ACCEPT`. | | `Authorization` | Não enviar | O endpoint público usa token na própria URL. Não envie chave da API Agilize nesse endpoint. | 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. ```json { "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: | Dado recebido | Variável para mapear | | --- | --- | | Nome do lead | `{{payload.lead.name}}` | | Telefone | `{{payload.lead.phone}}` | | E-mail | `{{payload.lead.email}}` | | Nome da empresa | `{{payload.company.name}}` | | Origem UTM | `{{payload.utm.source}}` | | ID do formulário | `{{payload.form.id}}` | | Tipo de evento | `{{payload.event}}` | ## 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](https://elementor.com/help/actions-after-submit/) e a documentação técnica de [Elementor Forms](https://developers.elementor.com/docs/hooks/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: ```text 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 | Plugin | Caminho prático | Atenção | | --- | --- | --- | | Elementor Pro Forms | Use a ação **Webhook** após envio do formulário. | Teste o formato recebido no debug. Para controle de JSON, validação e segurança, use ponte server-side. | | Gravity Forms | Use o **Webhooks Add-On**, configure um feed em `Form Settings > Webhooks`, método `POST`, formato `JSON`, URL da Agilize e corpo com campos selecionados. | A documentação oficial informa suporte a método, formato, headers, corpo e condições. Veja [Triggering Webhooks on Form Submissions](https://docs.gravityforms.com/triggering-webhooks-form-submissions/). | | WPForms | Use o **Webhooks Addon**, habilite em `Settings > Webhooks`, informe URL, método `POST` e formato `JSON`. | A documentação informa que o formato JSON define `Content-Type: application/json`. Veja [Webhooks Addon](https://wpforms.com/docs/how-to-install-and-use-the-webhooks-addon-with-wpforms/). | | Contact Form 7 | Use um plugin complementar, como **CF7 to Webhook**, ou uma customização no WordPress. | O Contact Form 7 puro normalmente exige plugin ou código para enviar webhook. O plugin CF7 to Webhook aceita URL de webhook e envio em JSON. Veja [CF7 to Webhook](https://wordpress.org/plugins/cf7-to-zapier/). | | Fluent Forms | Ative o módulo de webhooks e crie um webhook nas configurações do formulário. | Configure envio `POST` com JSON e valide o payload capturado. Veja [Webhook Integration with Fluent Forms](https://wpmanageninja.com/docs/fluent-form/integrations-available-in-wp-fluent-form/webhook-integration/). | | Formidable Forms | Use a ação **Send API Data** nas ações/notificações do formulário. | Configure URL, método e corpo JSON. Veja [Form Webhooks API](https://formidableforms.com/knowledgebase/formidable-api/). | | Ninja Forms | Use a extensão de webhooks para enviar submissões por `POST` para a URL da Agilize. | Configure JSON quando disponível e teste campos mapeados. Veja [Ninja Forms Webhooks](https://ninjaforms.com/docs/webhooks/). | 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: ```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 | Sintoma | Causa provável | Como corrigir | | --- | --- | --- | | Endpoint responde `ACCEPT`, mas nada aparece no CRM | Fluxo sem caminho completo, token ou webhook incorreto, ou node de criação não configurado. | Revise a URL, confira o início do fluxo e teste com debug. | | Debug não mostra o evento | Escuta do próximo evento não foi ativada, payload não chegou no endpoint correto ou o plugin enviou formato diferente de JSON. | Ative a escuta, copie novamente a URL e envie `Content-Type: application/json`. | | Lead duplicado | Deduplicação desativada ou telefone/e-mail mapeado em campo errado. | Ative verificação de duplicidade no node **Gerar Entidade** e revise `_phone` ou `_email`. | | Lead criado sem origem | Campo de origem ou UTM não foi enviado ou não foi mapeado. | Inclua `source`, `form.id` e `utm` no payload e preencha origem no node. | | Responsável errado | Usuário fixo, equipe ou mapeamento de usuário não correspondem à regra operacional. | Revise **Mapear Usuário**, equipe de distribuição e responsável do node de criação. | | Plugin de formulário não integra direto | Plugin envia formulário tradicional, não JSON, ou não permite headers. | Use uma ponte server-side para transformar e reenviar o payload. | ## Próximos passos - Consulte [Nodes de webhooks](/docs/configuracao/referencias/nodes-webhooks) para montar o fluxo visual. - Consulte [Rastreamento de UTM em leads e conversas WhatsApp](/docs/configuracao/canais-whatsapp-integracoes/rastreamento-utm-leads-whatsapp) para preservar dados de campanha. - Consulte [Automações de CRM](/docs/configuracao/fluxos-automacoes/automacoes-de-crm) quando o lead criado por webhook precisar iniciar cadências, tarefas ou movimentações posteriores.