Receber eventos no Muda | Muda Developers

Início rápido

Primeiro lead em menos de 10 minutos

O exemplo usa Bearer por ser o caminho mais simples para a primeira homologação. Em produção, prefira HMAC-SHA256 quando a ferramenta emissora conseguir assinar o corpo bruto.

1
Crie o endpoint na conexão correta
No Muda, abra Configurações → Conexões → canal → Webhooks. Crie o endpoint, escolha a autenticação e defina o funil e a etapa de destino antes de ativá-lo. Copie a URL completa e a credencial exibida.

2

Salve um payload de homologação

Crie um arquivo lead.json com dados sintéticos. Use um telefone controlado e exclusivo para o teste.

lead.json

json

{
  "id": "form_lead_12345_created_1784574000",
  "type": "lead.added",
  "version": "2026-07-01",
  "occurred_at": "2026-07-20T14:30:00.000Z",
  "source": "lead_form",
  "data": {
    "external_id": "form_lead_12345",
    "name": "Contato de homologacao",
    "email": "contato@example.invalid",
    "phone": "<telefone_internacional_exemplo_+55...>",
    "description": "Cargo: Gestor\nUnidades: 2\nPrazo: Nos proximos 30 dias\nOrganizacao atual: Planilhas e mensagens",
    "custom_fields": {
      "cargo": "Gestor",
      "unidades": 2,
      "prazo": "Nos proximos 30 dias",
      "organizacao_atual": "Planilhas e mensagens"
    }
  },
  "previous": null,
  "metadata": {
    "form_id": "form_synthetic",
    "campaign_id": "campaign_synthetic"
  }
}

3

Envie o evento

Substitua a URL e a credencial pelos valores copiados do Muda.

curl --request POST 'https://web.muda.chat/api/v1/webhooks/inbound/<endpoint_publico>' \
  --header 'Authorization: Bearer <credencial>' \
  --header 'Content-Type: application/json' \
  --data-binary '@lead.json'

Valide o recibo e o processamento
O HTTP 202 confirma que o evento foi autenticado e persistido. Depois, confira a aba Histórico do webhook para verificar se ele foi processado, deduplicado ou rejeitado.
Resposta HTTP 202
json
```
{
  "received": true,
  "accepted": 1,
  "duplicates": 0,
  "request_id": "00000000-0000-4000-8000-000000000000"
}
```

Formulários

Mapeie perguntas sem perder contexto

Campos principais ficam em propriedades canônicas. Perguntas comerciais ficam em custom_fields e podem preencher campos existentes do funil por meio do mapeamento do endpoint.

Mapeamento recomendado dos campos de formulário
Campo do formulário	Destino no JSON	Uso
Nome completo	`data.name`	Nome exibido no contato e no negócio
E-mail	`data.email`	E-mail do contato
Telefone	`data.phone`	Chave de localização do chat dentro da conexão
Cargo	`data.custom_fields.cargo`	Resposta original do formulário
Unidades	`data.custom_fields.unidades`	Quantidade informada
Prazo	`data.custom_fields.prazo`	Momento pretendido para começar
Organização atual	`data.custom_fields.organizacao_atual`	Como a operação funciona hoje

Modelo para mapear variáveis da automação

json com placeholders

{
  "id": "{{event_id_unico}}",
  "type": "lead.added",
  "version": "2026-07-01",
  "occurred_at": "{{data_hora_iso_8601}}",
  "source": "lead_form",
  "data": {
    "external_id": "{{lead_id_externo}}",
    "name": "{{nome_completo}}",
    "email": "{{email}}",
    "phone": "{{telefone}}",
    "description": "Cargo: {{cargo}}\nUnidades: {{unidades}}\nPrazo: {{prazo}}\nOrganizacao atual: {{organizacao_atual}}",
    "custom_fields": {
      "cargo": "{{cargo}}",
      "unidades": "{{unidades}}",
      "prazo": "{{prazo}}",
      "organizacao_atual": "{{organizacao_atual}}"
    }
  },
  "metadata": {
    "form_id": "{{form_id}}",
    "campaign_id": "{{campaign_id}}"
  }
}

Contrato 2026-07-01

Envelope JSON estrito

Envie um objeto ou um lote de até 100 eventos. Campos específicos da integração devem ficar dentro de data ou metadata.

Exemplo canônico de lead.added

json

{
  "id": "partner_lead_12345_created_1784574000",
  "type": "lead.added",
  "version": "2026-07-01",
  "occurred_at": "2026-07-20T14:30:00.000Z",
  "source": "partner_system",
  "data": {
    "external_id": "lead_12345",
    "name": "Contato de homologacao",
    "phone": "<telefone_internacional_exemplo_+55...>",
    "email": "contato@example.invalid",
    "stage_external_id": "stage_new",
    "custom_fields": {
      "campaign_name": "Campanha de homologacao",
      "form_name": "Formulario principal"
    }
  },
  "previous": null,
  "metadata": {
    "campaign_id": "campaign_synthetic",
    "correlation_id": "correlation_synthetic"
  }
}

id

Identificador idempotente do evento. Reutilize o mesmo valor nos retries.

type

Tipo canônico do catálogo, por exemplo lead.added.

version

Versão do envelope. Nesta documentação: 2026-07-01.

occurred_at

Data e hora ISO 8601 do acontecimento na origem.

source

Nome técnico genérico da origem. O Muda registra a origem segura do endpoint.

data

Campos da entidade e custom_fields específicos da integração.

previous

Valores anteriores quando fizer sentido para o evento.

metadata

Correlação, campanha, formulário e contexto semântico não sensível.

Segurança

Bearer para simplicidade, HMAC para integridade

Bearer

Envie Authorization: Bearer <credencial>. É adequado para plataformas que suportam cabeçalhos, mas não conseguem calcular HMAC.

HMAC-SHA256

Assine timestamp + "." + corpo_bruto_exato e envie emX-Muda-Signature. A tolerância atual é de 300 segundos.

Confiabilidade

Retries seguros e sem duplicação

1

Gere um id estável

Use o identificador do lead e o acontecimento na origem.

2

Mantenha o corpo

Em cada retry, envie exatamente o mesmo id e o mesmo payload.

3

Trate o recibo

Se duplicates for maior que zero, o evento já havia sido recebido.

Referência

Catálogo pesquisável de eventos

25 tipos têm aplicação local. Os demais continuam autenticados, idempotentes e registrados para auditoria.

32 eventos encontrados

Leads

lead.added

Lead adicionado

Aplica no CRM

lead.updated

Lead editado

Aplica no CRM

lead.deleted

Lead excluido

Aplica no CRM

lead.restored

Lead restaurado

Aplica no CRM

lead.stage_changed

Etapa do lead alterada

Aplica no CRM

lead.responsible_changed

Responsavel do lead alterado

Aplica no CRM

Contatos

contact.added

Contato adicionado

Aplica no CRM

contact.updated

Contato editado

Aplica no CRM

contact.deleted

Contato excluido

Aplica no CRM

contact.restored

Contato restaurado

Aplica no CRM

contact.responsible_changed

Responsavel do contato alterado

Aplica no CRM

Empresas

company.added

Empresa adicionada

Aplica no CRM

company.updated

Empresa editada

Aplica no CRM

company.deleted

Empresa excluida

Aplica no CRM

company.restored

Empresa restaurada

Aplica no CRM

company.responsible_changed

Responsavel da empresa alterado

Registra no histórico

Tarefas

task.added

Tarefa adicionada

Aplica no CRM

task.updated

Tarefa editada

Aplica no CRM

task.deleted

Tarefa excluida

Aplica no CRM

task.responsible_changed

Responsavel da tarefa alterado

Aplica no CRM

Leads de entrada

incoming_lead.added

Lead de entrada adicionado

Aplica no CRM

incoming_lead.updated

Lead de entrada editado

Aplica no CRM

incoming_lead.deleted

Lead de entrada excluido

Aplica no CRM

Mensagens

message.incoming

Mensagem recebida

Registra no histórico

Conversas

talk.added

Conversa adicionada

Registra no histórico

talk.updated

Conversa editada

Registra no histórico

Notas

note.lead_added

Nota adicionada ao lead

Registra no histórico

note.contact_added

Nota adicionada ao contato

Registra no histórico

note.company_added

Nota adicionada a empresa

Registra no histórico

Produtos

product.added

Produto adicionado

Aplica no CRM

product.updated

Produto editado

Aplica no CRM

product.deleted

Produto excluido

Aplica no CRM

Tipos somente para histórico nesta versão: company.responsible_changed, message.incoming, talk.added, talk.updated, note.lead_added, note.contact_added, note.company_added.

Operação

Respostas, retries e backoff

Faça retry apenas em falhas temporárias. Para erros de contrato ou autenticação, corrija a requisição antes de tentar novamente.

Respostas HTTP possíveis do endpoint de entrada
HTTP	Significado	Ação recomendada
`202`	Evento autenticado, validado e persistido	Não reenviar; consulte o histórico
`400`	JSON malformado	Corrigir o corpo
`401`	Assinatura ou token inválido	Revisar credencial, corpo bruto e relógio
`404`	Endpoint inexistente, pausado ou revogado	Revisar URL e ativação
`408`	Corpo não chegou no prazo	Reenviar com backoff e jitter
`409`	Mesmo id com payload diferente	Investigar a origem; não gerar novo efeito
`413`	Corpo acima do limite	Reduzir o payload
`415`	Content-Type incompatível	Enviar application/json
`422`	Envelope, campos ou evento inválido	Corrigir sem retry automático
`429`	Limite por minuto atingido	Respeitar Retry-After
`503`	Persistência temporariamente indisponível	Reenviar com o mesmo id

Downloads

Checklist

Antes de ativar em produção

Use somente HTTPS e mantenha a URL opaca em um cofre de segredos.
Nunca registre credenciais, payloads completos ou telefones sem máscara.
Prefira HMAC e sincronize o relógio do servidor emissor.
Implemente timeout, backoff exponencial com jitter e teto de tentativas.
Use dados sintéticos na homologação e confirme o endpoint da conexão correta.
Rotacione a credencial imediatamente se houver qualquer suspeita de exposição.

Receber leads e eventos no Muda

Primeiro lead em menos de 10 minutos

Crie o endpoint na conexão correta

Salve um payload de homologação

Envie o evento

Valide o recibo e o processamento

Mapeie perguntas sem perder contexto

Envelope JSON estrito

Bearer para simplicidade, HMAC para integridade

Bearer

HMAC-SHA256

Retries seguros e sem duplicação

Gere um id estável

Mantenha o corpo

Trate o recibo

Catálogo pesquisável de eventos

Leads

Contatos

Empresas

Tarefas

Leads de entrada

Mensagens

Conversas

Notas

Produtos

Respostas, retries e backoff

Teste e gere código a partir do mesmo contrato

Coleção Postman

Ambiente Postman

OpenAPI 3.1

JSON Schema

Antes de ativar em produção