Webhooks de Entrada

Endpoint Público

POST /webhooks/{token}
SEM AUTENTICAÇÃO

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

Exemplo de Payload

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

Resposta

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

Criar Webhook de Entrada

POST /backend/webhooks

Request Body

string

obrigatório

Nome do webhook

string

Descrição do webhook

string

obrigatório

Deve ser "inbound"

boolean

padrão:"true"

Se o webhook está ativo

object

obrigatório

Mapeamento de campos do payload para campos de lead

object

Mapeamento para campos personalizados

string

Status padrão para leads criados

array

Tags a serem adicionadas automaticamente

string

Pipeline onde criar um negócio para o lead recebido

string

Etapa onde o negócio deve entrar

Exemplo

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"]
  }'

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']
  })
});

Resposta

{
  "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:

// 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. Assim, leads vindos de um formulário ou de um anúncio caem automaticamente na pipeline. Basta configurar os dois campos de destino:

{
  "target_pipeline_id": "bb0e8400-e29b-41d4-a716-446655440000",
  "target_stage_id": "cc0e8400-e29b-41d4-a716-446655440000"
}

Os dois campos formam um par: informe ambos ou nenhum. Enviar só um deles retorna 400.

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

O negócio é criado depois do lead

O lead é criado ou atualizado primeiro. Só então o negócio é criado e vinculado a ele.

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.

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.

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".

Testar Webhook

POST /backend/webhooks/{id}/test

Envia um payload de teste para validar os mapeamentos.

{
  "payload": {
    "form": {
      "nome_completo": "Teste",
      "email": "teste@exemplo.com",
      "telefone": "+5511999999999"
    }
  }
}

Visão Geral

Leads

Status

Tags

Base de Conhecimento

Pipeline (CRM)

Webhooks

Campos Personalizados

Cadências

Conversas

Mensagens

Departamentos

Upload de Arquivos

Templates (Meta/Gupshup)

Follow-up

Webhooks de Entrada

Endpoint Público

Exemplo de Payload

Resposta

Criar Webhook de Entrada

Request Body

Exemplo

Resposta

Mapeamento de Campos

Campos Disponíveis

Notação de Ponto

Criar Negócio na Pipeline

Comportamento

Testar Webhook

​Endpoint Público

​Exemplo de Payload

​Resposta

​Criar Webhook de Entrada

​Request Body

​Exemplo

​Resposta

​Mapeamento de Campos

​Campos Disponíveis

​Notação de Ponto

​Criar Negócio na Pipeline

​Comportamento

​Testar Webhook

Endpoint Público

Exemplo de Payload

Resposta

Criar Webhook de Entrada

Request Body

Exemplo

Resposta

Mapeamento de Campos

Campos Disponíveis

Notação de Ponto

Criar Negócio na Pipeline

Comportamento

Testar Webhook