Webhooks de entrada

Receba dados externos no MIX sem precisar usar a API REST. Útil para conectar formulários, Zapier, n8n, ou qualquer backend que já chame webhooks pra ferramentas tipo "mais um destino".

Quando usar

• Formulários no seu site que não rodam em landing pages do MIX.
• Zapier / Make / n8n: qualquer ferramenta de automação no-code que dispara webhook como ação.
• Backend legado que já posta pra Slack/HubSpot e você quer adicionar o MIX sem refatorar.

Criar um inbound webhook

1. No app, vá em Configurações → Webhooks → Entrada.
2. Clique em Novo webhook de entrada.
3. Defina:
   • Nome: ex.: "Formulário lead-magnet".
   • Tipo de objeto: person ou deal (companies não são suportados como destino direto na v1 atual: crie uma person e o sistema linka via domínio).
   • Mapeamento de campos: pra cada campo do payload externo, qual campo do MIX ele alimenta.
   • Estratégia de dedup: email (se vier um e-mail já cadastrado, faz UPDATE em vez de criar duplicata) ou none.
   • Ações pós-recepção: atribuir owner, adicionar tags, criar deal automaticamente.
4. Copie a URL gerada. Formato:
   textCopiar

   https://api.usemix.app/webhooks/in/<token>

Enviar dados

POST com JSON. Não há autenticação por header: o token na URL é a credencial.

curl -X POST https://api.usemix.app/webhooks/in/<token> \
  -H "Content-Type: application/json" \
  -d '{
    "nome_completo": "João Pereira",
    "email": "joao@startup.com.br",
    "empresa": "Startup Inc"
  }'

Se o mapeamento bate (campo email mapeado para primaryEmail), uma pessoa nova é criada e você recebe 201:

{ "ok": true, "personId": "1f0c87e8-..." }

Exemplo de payload externo

Imagine que seu formulário envia:

{
  "nome_completo": "João Pereira",
  "email": "joao@startup.com.br",
  "telefone": "+5511988887777",
  "empresa": "Startup Inc",
  "interesse": "implementação completa",
  "utm_source": "google",
  "utm_campaign": "lead-magnet-q2"
}

E você configurou o mapeamento como:

{
  "fullName": "{{nome_completo}}",
  "primaryEmail": "{{email}}",
  "primaryPhone": "{{telefone}}",
  "leadSource": "zapier",
  "customFields": {
    "interesse_inicial": "{{interesse}}",
    "utm_source": "{{utm_source}}",
    "utm_campaign": "{{utm_campaign}}"
  }
}

O resultado é uma pessoa criada com fullName: "João Pereira", primaryEmail: "joao@startup.com.br", e os campos de UTM viram custom fields. Sem código.

Deduplicação

Estratégias suportadas em Configurações → Webhooks de entrada:

• email: se já existe pessoa com esse primaryEmail, faz UPDATE merge com os campos novos. Recomendado para 99% dos casos.
• phone: mesmo, mas por primaryPhone.
• composite: combinação de campos (ex.: e-mail + nome). Configurada no app web.
• none: sempre cria duplicata. Útil quando você quer rastrear cada submit (ex.: histórico de submissões).

Erros comuns

• 404 not_found: token revogado ou inválido.
• 422 validation_error: payload não bate com o mapeamento (campo obrigatório ausente após mapping). Veja details.field.
• 429: o limite global de 300 req/min se aplica também a inbound.