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

# Webhooks de Entrada

> Receba dados de sistemas externos

## Endpoint Público

<Card className="border-2 border-green-500">
  <strong>POST</strong> `/webhooks/{token}`

  <br />

  <span className="text-green-600 font-bold">SEM AUTENTICAÇÃO</span>
</Card>

Este endpoint é público e não requer autenticação. Use o token único do webhook para identificação.

## Exemplo de Payload

```json theme={null}
{
  "form": {
    "nome_completo": "João Silva",
    "email": "joao@exemplo.com",
    "telefone": "+5511999999999",
    "empresa": "Empresa XYZ",
    "produto_interesse": "Plano Premium"
  }
}
```

## Resposta

```json theme={null}
{
  "success": true,
  "lead_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Lead created/updated successfully"
}
```

***

## Criar Webhook de Entrada

<Card>
  <strong>POST</strong> `/backend/webhooks`
</Card>

### Request Body

<ParamField body="name" type="string" required>
  Nome do webhook
</ParamField>

<ParamField body="description" type="string">
  Descrição do webhook
</ParamField>

<ParamField body="type" type="string" required>
  Deve ser `"inbound"`
</ParamField>

<ParamField body="is_active" type="boolean" default="true">
  Se o webhook está ativo
</ParamField>

<ParamField body="field_mapping" type="object" required>
  Mapeamento de campos do payload para campos de lead
</ParamField>

<ParamField body="custom_field_mapping" type="object">
  Mapeamento para campos personalizados
</ParamField>

<ParamField body="default_status_id" type="string">
  Status padrão para leads criados
</ParamField>

<ParamField body="default_tags" type="array">
  Tags a serem adicionadas automaticamente
</ParamField>

<ParamField body="target_pipeline_id" type="string">
  Pipeline onde criar um negócio para o lead recebido
</ParamField>

<ParamField body="target_stage_id" type="string">
  Etapa onde o negócio deve entrar
</ParamField>

### Exemplo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.leavo.ai/backend/webhooks" \
    -H "Authorization: Bearer sua_chave_aqui" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Webhook Formulário Site",
      "description": "Recebe leads do formulário do site",
      "type": "inbound",
      "is_active": true,
      "field_mapping": {
        "name": "form.nome_completo",
        "email": "form.email",
        "phone": "form.telefone",
        "company": "form.empresa"
      },
      "custom_field_mapping": {
        "interesse": "form.produto_interesse"
      },
      "default_status_id": "uuid-do-status",
      "default_tags": ["uuid-tag-1", "uuid-tag-2"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.leavo.ai/backend/webhooks', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sua_chave_aqui',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Webhook Formulário Site',
      description: 'Recebe leads do formulário do site',
      type: 'inbound',
      is_active: true,
      field_mapping: {
        name: 'form.nome_completo',
        email: 'form.email',
        phone: 'form.telefone',
        company: 'form.empresa'
      },
      custom_field_mapping: {
        interesse: 'form.produto_interesse'
      },
      default_status_id: 'uuid-do-status',
      default_tags: ['uuid-tag-1', 'uuid-tag-2']
    })
  });
  ```
</CodeGroup>

### Resposta

```json theme={null}
{
  "id": "uuid",
  "tenant_id": "uuid",
  "name": "Webhook Formulário Site",
  "webhook_token": "abc123xyz",
  "type": "inbound",
  "is_active": true,
  "total_calls": 0,
  "created_at": "2024-01-01T00:00:00Z"
}
```

***

## Mapeamento de Campos

### Campos Disponíveis

| Campo     | Descrição                          |
| --------- | ---------------------------------- |
| `name`    | Nome completo do lead              |
| `surname` | Sobrenome do lead                  |
| `email`   | Email do lead                      |
| `phone`   | Telefone do lead (**obrigatório**) |
| `company` | Empresa do lead                    |

### Notação de Ponto

Use notação de ponto para acessar campos aninhados:

```json theme={null}
// Payload recebido
{
  "customer": {
    "contact": {
      "email": "joao@exemplo.com"
    }
  }
}

// Mapeamento
{
  "email": "customer.contact.email"
}
```

***

## Criar Negócio na Pipeline

Um webhook de entrada pode, além de criar/atualizar o lead, colocá-lo direto no quadro do
[CRM](/pt-BR/api-reference/pipeline/overview). Assim, leads vindos de um formulário ou de um
anúncio caem automaticamente na pipeline.

Basta configurar os dois campos de destino:

```json theme={null}
{
  "target_pipeline_id": "bb0e8400-e29b-41d4-a716-446655440000",
  "target_stage_id": "cc0e8400-e29b-41d4-a716-446655440000"
}
```

<Warning>
  Os dois campos formam um **par**: informe **ambos ou nenhum**. Enviar só um deles retorna
  **400**.
</Warning>

Para **desativar** a criação de negócios em um webhook existente, envie
`target_pipeline_id` com o UUID zerado (`00000000-0000-0000-0000-000000000000`) — isso limpa
os dois campos.

### Comportamento

<AccordionGroup>
  <Accordion title="O negócio é criado depois do lead">
    O lead é criado ou atualizado primeiro. Só então o negócio é criado e vinculado a ele.
  </Accordion>

  <Accordion title="Falhas nunca derrubam a entrada do lead">
    Se a criação do negócio falhar — etapa excluída, pipeline removida, configuração inválida —
    o erro é registrado no log e a requisição **continua retornando sucesso**. Receber o lead é
    a função principal do webhook; o negócio é um bônus.
  </Accordion>

  <Accordion title="A etapa de destino não pode ser a de perda">
    Um webhook nunca cria negócios já perdidos em silêncio. Uma etapa `lost` como destino é
    recusada.
  </Accordion>

  <Accordion title="O histórico registra um autor de sistema">
    Como não existe usuário autenticado na chamada do webhook, o evento `deal_created` aparece
    no histórico com `actor_type: "system"`.
  </Accordion>
</AccordionGroup>

***

## Testar Webhook

<Card>
  <strong>POST</strong> `/backend/webhooks/{id}/test`
</Card>

Envia um payload de teste para validar os mapeamentos.

```json theme={null}
{
  "payload": {
    "form": {
      "nome_completo": "Teste",
      "email": "teste@exemplo.com",
      "telefone": "+5511999999999"
    }
  }
}
```