> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flunora.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook do Meta Lead Ads

> O endereço que recebe os eventos da Meta, a verificação inicial e a assinatura de cada entrega.

Este endereço é operado pela conexão de Facebook do produto. A configuração normal é
feita em **Configurações → Integrações → Facebook**, e esta página existe para quem
precisa entender o caminho ou depurá-lo.

<Card title="Como conectar" href="/entradas/meta-lead-ads" horizontal>
  O passo a passo pela interface, que é o caminho recomendado.
</Card>

## Verificação

Ao registrar o endereço no painel da Meta, ela faz uma chamada de verificação:

```
GET /api/webhooks/facebook-leads?hub.mode=subscribe&hub.verify_token=...&hub.challenge=...
```

Quando o token confere, a resposta é **exatamente** o valor de `hub.challenge`, em texto
puro. Qualquer coisa a mais, inclusive aspas de JSON, faz a Meta recusar o endereço.

## Recebimento

```
POST /api/webhooks/facebook-leads
```

Cada entrega é assinada. O cabeçalho `x-hub-signature-256` traz um HMAC-SHA256 do corpo
cru, calculado com o segredo do aplicativo, e a assinatura é conferida **antes** de o
corpo ser interpretado.

<Warning>
  A conferência usa o corpo exatamente como recebido. Qualquer intermediário que
  reformate o JSON no caminho quebra a assinatura, e a entrega passa a ser recusada.
</Warning>

## O que acontece a cada evento

<Steps>
  <Step title="A página é identificada">
    O identificador da página no evento é comparado com as conexões cadastradas. Página
    desconhecida é ignorada.
  </Step>

  <Step title="Os dados do formulário são buscados">
    O evento traz só a referência. O conteúdo é buscado na API da Meta com o token de
    acesso da página, guardado cifrado na conexão.
  </Step>

  <Step title="Os campos são mapeados">
    Nome, email, telefone e empresa, nas variações em português e em inglês. O que não
    tem destino conhecido vai para a observação do contato.
  </Step>

  <Step title="O contato entra">
    Na etapa de entrada do funil padrão, atribuído ao primeiro dono ou administrador da
    organização, com campanha, conjunto, anúncio e formulário preenchidos.
  </Step>
</Steps>

## Depurar

O caminho tem três pontos de falha, e eles se distinguem pelo sintoma:

| Sintoma                                       | Causa provável                                                                          |
| --------------------------------------------- | --------------------------------------------------------------------------------------- |
| A Meta recusa o endereço no registro          | Token de verificação diferente do configurado                                           |
| Eventos chegam e nada aparece no CRM          | Assinatura recusada, ou a página do evento não corresponde a nenhuma conexão            |
| O contato aparece sem os campos do formulário | O token de acesso da página perdeu validade, ou falta a permissão de recuperar contatos |

O terceiro é o mais comum e o mais silencioso. A tela de integrações passa a pedir
religação quando isso acontece.

<Note>
  A ferramenta de teste da Meta cria um contato de mentira que percorre exatamente o
  mesmo caminho. É o jeito mais rápido de provar que a ponta inteira está de pé.
</Note>