Skip to main content
Todo evento enviado ao webhook receiver segue o mesmo envelope. O campo event identifica o tipo; customer carrega o cliente final; metadata opcionalmente enriquece o contexto.

​
Envelope

{
  "event": "subscription.cancelled",
  "customer": {
    "external_id": "usr_42",
    "name": "Maria Silva",
    "email": "maria@empresa.com.br",
    "phone": "+5511999999999"
  },
  "metadata": {
    "reason": "too_expensive"
  }
}

​
Campos

CampoTipoObrigatórioDescrição
eventstringsimNome do evento no formato namespace.verb. Precisa ser um dos 9 gatilhos ou 22 trackings listados adiante.
customer.external_idstringsimIdentificador do cliente no seu SaaS. Mínimo 1 caractere.
customer.namestringsimNome do cliente. Mínimo 1 caractere.
customer.emailstringsimE-mail válido.
customer.phonestringdependeFormato E.164 (+5511999999999). Obrigatório em eventos de gatilho, opcional em tracking.
metadataobjectnãoJSON arbitrário. Limite de 32 KB após serialização. Campos úteis por evento são sugeridos nas páginas de catálogo.

​
Gatilho vs tracking

  • Gatilho (9 eventos) — phone é obrigatório. Disparam o agente. Listados em Eventos de gatilho.
  • Tracking (22 eventos) — phone é opcional. Não disparam conversa imediata, mas alimentam a detecção preditiva. Listados em Eventos de tracking.

​
Validação de telefone (E.164)

O phone precisa começar com + seguido do código do país e do número, sem espaços nem caracteres especiais. Exemplo: +5511999999999. Números sem +, sem código de país ou com caracteres inválidos causam resposta 422 com error.code igual a VALIDATION_ERROR.