Conecte o Funnim ao seu processo comercial.

Hoje a integração do Funnim com sistemas externos acontece principalmente por webhooks: cada funil pode disparar uma automação que envia os dados do lead para uma URL sua assim que ele responde, atualiza ou conclui o funil. Além disso, o funil aceita alguns pontos de personalização que também interessam a quem desenvolve: parâmetros de UTM na URL, scripts de rastreamento de terceiros, e um bloco de HTML livre com um callback em JavaScript para controlar o avanço do funil.

Não existe hoje uma API REST pública para criar ou editar funis por código, nem uma chave de API para chamadas autenticadas de fora — veja a seção Limitações atuais para o que ainda não está disponível.

Configurados na aba Automações do editor do funil: você escolhe um gatilho (evento), uma condição opcional e a ação webhook com a URL de destino. Quando o gatilho acontece, o Funnim faz um POST com Content-Type: application/json para essa URL.

Gatilhos disponíveis

Headers enviados

• X-Funnim-Event — nome do evento (ex: response.completed)
• X-Funnim-Delivery — id único desta entrega, útil para deduplicar
• X-Funnim-Timestamp — horário do envio (epoch, segundos)
• X-Funnim-Signature — assinatura HMAC do corpo (ver Autenticidade)
• User-Agent: Funnim-Webhooks/1.0

Exemplo de payload

{
  "id": "evt_9f1a3c2e-...",
  "delivery_id": "del_7e4d2b31-...",
  "event": "response.completed",
  "payload_version": "2026-07-03",
  "created_at": "2026-07-04T18:32:10.482Z",
  "data": {
    "event": "response.completed",
    "funil_id": "37f336a4-6f2d-486b-856a-27685bb6f136",
    "funil_nome": "Diagnóstico de Maturidade Comercial",
    "lead": {
      "id": "b7f1...",
      "nome": "Ana Souza",
      "email": "ana@empresa.com",
      "phone": "5511999999999",
      "perfil": "Pronta para escalar",
      "perfil_id": "perfil_2",
      "pontuacao": 87,
      "resumo_comercial": "Já validou a oferta e tem tráfego ativo...",
      "tags": ["urgencia_alta", "ticket_medio"],
      "utms": {
        "utm_source": "instagram",
        "utm_medium": "cpc",
        "utm_campaign": "lancamento_julho",
        "utm_term": null,
        "utm_content": null,
        "referrer": null
      },
      "respostas": [
        {
          "etapa_id": "et_3",
          "tipo": "pergunta_unica",
          "pergunta": "Qual seu faturamento mensal?",
          "resposta": "Entre R$ 10 mil e R$ 50 mil",
          "pontos": 15
        }
      ],
      "campos_personalizados": {
        "cargo": "CEO",
        "faturamento_mensal": "R$ 32.000"
      },
      "created_at": "2026-07-04T18:31:52.011Z"
    },
    "response": { "id": "res_...", "status": "concluida", "..." : "mesmos campos do lead" }
  },
  "context": {
    "workspace_id": "...",
    "funil_id": "37f336a4-...",
    "lead_id": "b7f1...",
    "response_id": "res_...",
    "automation": { "id": "aut_1", "name": "Enviar pro CRM", "trigger": "response.completed" },
    "action": { "id": "acao_1", "type": "webhook" }
  }
}

Timeout de 6 segundos. Se sua URL não responder a tempo, a entrega é considerada falha. Hoje não há reentrega automática — cada disparo é uma tentativa única, então sua URL deve responder rápido (idealmente 200 em menos de 1s) e processar o resto de forma assíncrona do seu lado.

Use o botão Testar webhook na aba Automações para disparar um payload de exemplo (eventowebhook.test) contra a sua URL antes de colocar em produção.

Todo webhook carrega o header X-Funnim-Signature no formato v1={hex}, um HMAC-SHA256 calculado sobre ${timestamp}.${body}.

Qualquer pergunta do funil pode ser marcada com um nome de campo (na configuração da etapa, no editor). A resposta passa a aparecer no lead com esse nome, tanto no CSV quanto no webhook, dentro de lead.campos_personalizados e response.campos_personalizados.

Regras de nome

• Só letras minúsculas, números e _ — acentos e espaços são convertidos automaticamente (ex: “Faturamento Mensal” → faturamento_mensal)
• Único por funil — duas etapas não podem usar o mesmo nome
• Não pode usar um nome já reservado para campo padrão do lead: id, nome, email, phone, whatsapp, pontuacao, perfil, perfil_id, tags, utms, temperatura, resumo_comercial, criado_em

No CSV exportado, cada campo personalizado em uso vira uma coluna própria — as colunas são calculadas dinamicamente a partir de todas as respostas exportadas.

O Funnim captura automaticamente utm_source, utm_medium, utm_campaign,utm_term, utm_content e o referrer da URL quando o funil carrega — basta adicionar os parâmetros na URL que você já usa para anunciar (ex: ?utm_source=instagram&utm_medium=cpc).

Esses dados chegam completos no webhook (lead.utms) e no detalhe do lead no dashboard. No CSV exportado hoje só aparecem utm_source, utm_medium e utm_campaign — se precisar de utm_term/utm_content/referrer, use o webhook ou a tela de detalhe do lead.

As rotas públicas que recebem tráfego direto do participante têm limite por IP, para proteger contra abuso. Isso não afeta webhooks recebidos por você (que partem do Funnim) — só as rotas que o próprio funil chama.

Em Configurações → Rastreamento, o funil aceita Meta Pixel, Google Analyticse GTM por campos dedicados (só o ID), além de um campo de scripts personalizados que aceita qualquer HTML/JS — útil para Hotjar, Clarity, pixels de afiliado ou qualquer outra tag. Esse conteúdo é injetado no <head> da página do funil publicado.

O bloco HTML livre do editor renderiza seu HTML/CSS/JS dentro de um iframe isolado. Se você desativar o botão padrão de avançar (“Tem botão de avançar”), seu script controla quando o funil continua chamando uma função exposta automaticamente no escopo do iframe:

window.funnelNext();

Isso é o suficiente para embutir um player de vídeo (VSL), um quiz próprio ou qualquer widget interativo que precise decidir quando o participante está pronto para a próxima etapa.

Qualquer funil pode ser aberto com ?preview=true na URL (o botão “Pré-visualizar” do editor já faz isso). Nesse modo, nenhum lead é salvo, nenhuma automação dispara e nenhum script de rastreamento roda — é o jeito oficial de testar sua integração de webhook ou seu HTML livre sem sujar métricas ou disparar automações de verdade.

• Não há API pública para criar, editar ou listar funis por código.
• Não há chave de API para chamadas autenticadas externas — o acesso ao dashboard é só por sessão de login.
• Reentrega automática de webhook (retry) ainda não está ativa — cada disparo é uma tentativa única.
• Verificação de assinatura (X-Funnim-Signature) ainda não é possível pelo cliente — a chave não é exposta por workspace.
• Não há gerador de código de embed (iframe) para colocar o funil dentro de outro site — hoje o funil vive na própria URL do Funnim.