Webhook de entrada

Criar um contato

string

required

O token de 48 caracteres do webhook, no caminho da URL.

POST /api/webhooks/receive/{token}

Cabeçalhos aceitos

`Content-Type`	Uso
`application/json`	Recomendado
`application/x-www-form-urlencoded`	Formulário HTML tradicional
`multipart/form-data`	Formulário com upload; só os campos de texto são lidos

Sem Content-Type reconhecido, o corpo é tentado como JSON.

Corpo

Os nomes de campo são reconhecidos em português e em inglês, com as variações mais comuns. A lista completa está em Campos aceitos.

string

required

Precisa conter @. É o único campo obrigatório.

string

Sem ele, o contato entra como “Lead sem nome”.

string

Qualquer formatação é aceita.

string

number | string

Convertido para número. O que não converte vira zero.

string

Vai para a observação do contato.

string

Se o texto corresponder a uma origem cadastrada na organização, sem diferenciar maiúscula de minúscula, o contato é ligado a ela. Quando o webhook já tem origem fixa configurada, ela vence e este campo é ignorado.

Exemplos

curl -X POST https://crm.suaempresa.com/api/webhooks/receive/SEU_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Joana Ribeiro",
    "email": "joana@empresa.com.br",
    "telefone": "(11) 99999-9999",
    "empresa": "Empresa ABC",
    "mensagem": "Quer entender a implantação"
  }'

await fetch("https://crm.suaempresa.com/api/webhooks/receive/SEU_TOKEN", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    nome: "Joana Ribeiro",
    email: "joana@empresa.com.br",
    telefone: "11999999999",
    mensagem: "Quer entender a implantação",
  }),
});

import requests

requests.post(
    "https://crm.suaempresa.com/api/webhooks/receive/SEU_TOKEN",
    json={
        "nome": "Joana Ribeiro",
        "email": "joana@empresa.com.br",
        "telefone": "11999999999",
        "mensagem": "Quer entender a implantação",
    },
    timeout=30,
)

<?php
$ch = curl_init('https://crm.suaempresa.com/api/webhooks/receive/SEU_TOKEN');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'nome' => 'Joana Ribeiro',
    'email' => 'joana@empresa.com.br',
    'telefone' => '11999999999',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

<form action="https://crm.suaempresa.com/api/webhooks/receive/SEU_TOKEN" method="POST">
  <input type="text" name="nome" placeholder="Nome" required />
  <input type="email" name="email" placeholder="Email" required />
  <input type="tel" name="telefone" placeholder="Telefone" />
  <textarea name="mensagem" placeholder="Mensagem"></textarea>
  <button type="submit">Enviar</button>
</form>

Resposta

boolean

string

O identificador do contato criado.

string

200

{
  "success": true,
  "leadId": "clx1234567890abcdef",
  "message": "Lead created successfully"
}

Os códigos de erro estão em Erros.

Verificar o webhook

GET /api/webhooks/receive/{token}

Diz se o webhook existe e está ativo, sem criar nada. Use para testar a conexão depois de configurar.

curl https://crm.suaempresa.com/api/webhooks/receive/SEU_TOKEN

{
  "status": "ok",
  "name": "Formulário do site",
  "type": "generic",
  "enabled": true
}

A verificação responde mesmo com o webhook desligado, dizendo enabled: false. É o POST que recusa nesse caso.

Tipos de webhook

generic
typeform

Aceita qualquer JSON ou formulário. Os campos são reconhecidos pelos nomes documentados em Campos aceitos.

O que acontece do lado de cá

Validação

O email é conferido. Sem @, a requisição é recusada e nada é criado.

Criação

O contato entra na etapa de entrada do funil padrão da organização.

Atribuição

Fica com o primeiro membro ativo da organização, preferindo dono, depois administrador, depois o mais antigo.

Origem

A origem fixa do webhook vence; na ausência dela, o texto enviado é comparado com as origens cadastradas.

Rastro

Uma notificação vai para a equipe, uma entrada é criada no histórico do contato nomeando o webhook, e o contador de recebidos do webhook sobe.

Automações

As automações de contato criado disparam. Veja Automações.

Limites

Não há limite de requisições por padrão. Isso é conveniente e é também o motivo de o token merecer cuidado: acompanhe o contador de recebidos e regere o token ao primeiro sinal de abuso.

Requisições devem completar em até trinta segundos. Uploads em multipart/form-data são aceitos, mas o arquivo é ignorado: só os campos de texto entram.

Introdução

Receber contatos

Webhook de entrada

Criar um contato

Cabeçalhos aceitos

Corpo

Exemplos

Resposta

Verificar o webhook

Tipos de webhook

O que acontece do lado de cá

Limites

​Criar um contato

​Cabeçalhos aceitos

​Corpo

​Exemplos

​Resposta

​Verificar o webhook

​Tipos de webhook

​O que acontece do lado de cá

​Limites

Criar um contato

Cabeçalhos aceitos

Corpo

Exemplos

Resposta

Verificar o webhook

Tipos de webhook

O que acontece do lado de cá

Limites