Webhooks no Chatys: integre qualquer sistema

O que é um Webhook e quando usar

Um webhook é uma forma de o Chatys notificar seu sistema externo em tempo real quando algo acontece — sem que você precise ficar consultando a API periodicamente. Em vez de perguntar "tem algo novo?", o Chatys empurra a informação automaticamente para uma URL do seu servidor assim que o evento ocorre.

Quando usar webhooks em vez de polling:

• Você quer atualizar um CRM ou ERP imediatamente quando uma nova conversa chega
• Precisa criar um ticket no Zendesk, Jira ou sistema próprio quando um lead é qualificado
• Quer acionar automações (email, SMS, notificação interna) baseadas em eventos do Chatys
• Precisa sincronizar dados com um sistema legado sem usar Zapier ou Make
• Deseja construir integrações personalizadas com controle total sobre o fluxo

Eventos disponíveis

O Chatys pode disparar webhooks para os seguintes eventos:

• message.received — Nova mensagem recebida de um contato (qualquer canal)
• message.sent — Mensagem enviada por agente ou IA para um contato
• conversation.created — Nova conversa iniciada (primeiro contato ou após encerramento)
• conversation.closed — Conversa marcada como encerrada por agente ou IA
• conversation.assigned — Conversa atribuída a um agente ou time específico
• tag.applied — Tag aplicada a uma conversa ou contato
• lead.qualified — Agente IA identificou e qualificou um lead conforme critérios configurados
• contact.created — Novo contato adicionado ao CRM do Chatys
• contact.updated — Dados de um contato existente foram atualizados
• ai.handoff — Agente IA transferiu a conversa para atendimento humano

Como criar um Webhook no Chatys

Formato do Payload JSON

Cada evento enviado pelo Chatys segue o mesmo formato base:

{
  "event": "message.received",
  "timestamp": "2025-01-15T14:32:00.000Z",
  "account_id": "acc_abc123",
  "data": {
    "conversation_id": "conv_xyz789",
    "contact": {
      "id": "contact_456",
      "name": "Maria Silva",
      "phone": "+5511999887766",
      "email": "maria@email.com",
      "tags": ["cliente", "vip"]
    },
    "message": {
      "id": "msg_001",
      "type": "text",
      "content": "Olá, gostaria de saber sobre os planos",
      "channel": "whatsapp",
      "direction": "inbound",
      "created_at": "2025-01-15T14:32:00.000Z"
    },
    "assigned_agent": {
      "id": "agent_789",
      "name": "João Atendente"
    }
  }
}

Para o evento lead.qualified, o campo data incluirá adicionalmente:

"lead": {
  "score": 85,
  "qualification_reason": "interesse confirmado, orçamento definido",
  "custom_fields": {
    "produto_interesse": "Plano Profissional",
    "orcamento": "R$ 500-1000/mês"
  }
}

Como validar a assinatura HMAC

Para garantir que as requisições vêm realmente do Chatys e não de terceiros, valide a assinatura em cada request recebido:

Exemplo em Node.js:

const crypto = require('crypto');

function validateSignature(body, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(body, 'utf8');
  const digest = 'sha256=' + hmac.digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(digest),
    Buffer.from(signature)
  );
}

// No handler do webhook:
const isValid = validateSignature(
  req.rawBody,        // corpo bruto, antes de parsear JSON
  req.headers['x-chatys-signature'],
  process.env.WEBHOOK_SECRET
);
if (!isValid) return res.status(401).send('Unauthorized');

Como testar um Webhook

Retry automático em caso de falha

O Chatys tem um sistema de retry automático para garantir que eventos não se percam:

• 1ª tentativa: imediatamente após o evento
• 2ª tentativa: 5 minutos após a falha
• 3ª tentativa: 30 minutos após
• 4ª tentativa: 2 horas após
• 5ª tentativa: 6 horas após — última tentativa

Se todas as tentativas falharem, o evento é marcado como "Falha permanente" no log e um alerta é enviado por email para o Admin da conta. O endpoint é temporariamente desativado se a taxa de falha ultrapassar 50% em 1 hora.

Usando webhooks para integrar com CRM e ERP

O caso de uso mais comum de webhooks no Chatys é a sincronização bidirecional com sistemas de CRM e ERP:

• Chatys → CRM: quando um contato é criado ou atualizado no Chatys, use o evento contact.created ou contact.updated para criar/atualizar o registro no seu CRM (Salesforce, HubSpot, RD Station, etc.)
• Lead qualificado → CRM: use lead.qualified para criar automaticamente uma oportunidade de venda no CRM com os dados capturados pelo Agente IA
• Conversa encerrada → ERP: use conversation.closed para criar um registro de atendimento no ERP e atualizar o histórico do cliente
• Tag aplicada → segmentação: use tag.applied para mover contatos entre listas de email marketing ou segmentos no CRM