Skip to main content
Um webhook de entrada é o caminho inverso da API: em vez de você chamar o Whatix, um sistema externo (formulário, CRM, planilha) manda dados pra o Whatix, que vira card, contato ou dispara um flow — sem você escrever código de integração.
Isso é diferente da API pública (/wapi): não usa Authorization: Bearer, não tem escopo, e não é você quem chama — é o seu sistema externo que recebe a URL e faz o POST.

​
Como criar

1

Crie o webhook no painel

Vá em API (menu lateral) → aba Webhooks e crie um novo. Escolha a ação: criar card (create_opportunity), disparar flow (trigger_flow) ou sincronizar contato (upsert_contact). O painel gera uma URL pública com um hash não-adivinhável — copie a URL exibida ali, não monte ela manualmente.
2

Configure o fieldMapping

O fieldMapping traduz os caminhos do JSON que o sistema externo manda pros campos que o Whatix entende. Cada valor é um dot-path dentro do payload recebido:Se o formulário externo manda:
O mapeamento configurado no painel seria phone → lead.telefone, contactName → lead.nome, title → interesse.
3

Teste com cURL

Use a URL copiada do painel no passo 1:
A resposta é imediata (202), antes de qualquer processamento:

​
O que acontece depois do 202

O 202 só confirma que o Whatix recebeu o payload — o processamento roda em background logo em seguida:
  • create_opportunity: resolve o contato pelo phone (reaproveita se o número já existe, cria se não), cria o card no pipeline/etapa/origem configurados no webhook e aplica os campos personalizados de custom, se houver.
  • trigger_flow: resolve o contato, abre um ticket na conexão configurada no webhook e roda o flow. As variáveis nativas do flow ficam disponíveis normalmente ({{nome}}, {{telefone}}, {{protocolo}}, {{data}}, {{hora}}, resolvidas do contato/ticket) — mas o payload bruto recebido no webhook não vira variável do flow.
  • upsert_contact: cria ou atualiza o contato com name/email/document, sem criar card nem disparar flow.
O payload recebido não é exposto como {{variables.*}} dentro do flow — hoje ele só é usado internamente para resolver o contato (fieldMapping.phone/contactName). Se o flow precisa de um dado específico do payload (ex.: o interesse do lead), leve-o pro contato via fieldMapping (inclusive custom.<nome-do-campo> em create_opportunity) antes de disparar o flow, ou trate o dado direto no seu sistema de origem.
Se fieldMapping.phone não resolver um telefone válido no payload recebido, o processamento falha silenciosamente do ponto de vista de quem chamou — a resposta já foi 202. Use o histórico da tela do webhook no painel (que registra corpo cru e resultado de cada chamada) para depurar um mapeamento incorreto.

​
Autenticação opcional e limites

  • Por padrão o webhook não exige nada além do hash (authMode: none). Você pode configurar um token no painel e exigi-lo no header X-Whatix-Token.
  • Um hash inativo ou inexistente responde 404.
  • Rate limit próprio de 120 requisições por minuto por hash (independente do rate limit de token da API /wapi) — passou disso, 429.
  • Para evitar duplicar o card/contato em caso de reenvio (retry do sistema externo), mande uma chave de idempotência: os headers Idempotency-Key ou X-Idempotency-Key, ou os campos idempotency_key, event_id/eventId no corpo (o primeiro valor encontrado, nessa ordem, é usado) — chamadas repetidas com a mesma chave dentro de 1 hora são ignoradas, e a resposta vem com duplicate: true (em vez de reprocessar) pra você identificar isso do seu lado.

​
Erros comuns

Para consumir dados do Whatix pela API tradicional (com token e escopos), veja Autenticação e os demais guias.