Webhooks e Eventos

Os Webhooks são a forma como a QuettaCode notifica sua aplicação sobre eventos em tempo real, como o recebimento de uma mensagem no WhatsApp.

Configuração

Você deve configurar uma URL HTTPS pública no seu painel ou via API. A QuettaCode enviará requisições POST para essa URL com um payload JSON.

Formato do Payload

Todos os eventos seguem um envelope padrão:

{
  "event": "message.received",
  "id": "evt_123456789",
  "timestamp": "2023-10-27T10:00:00Z",
  "tenantId": "tenant_abc",
  "data": {
    // ... dados específicos do evento
  }
}

Principais Eventos

message.received

Disparado quando uma nova mensagem chega de um contato.

{
  "event": "message.received",
  "data": {
    "channelId": "chan_123",
    "contact": {
      "id": "ct_999",
      "phone": "5511999999999",
      "name": "João Silva"
    },
    "message": {
      "id": "msg_wam_123",
      "type": "text",
      "content": "Olá, gostaria de um orçamento."
    }
  }
}

message.status

Atualizações de status de entrega (enviado, entregue, lido, falha).

{
  "event": "message.status",
  "data": {
    "messageId": "msg_wam_123",
    "status": "read", // sent, delivered, read, failed
    "error": null
  }
}

channel.status

Mudanças na conexão do canal (ex: desconectado, banido).

Segurança (Assinatura)

Para garantir que o webhook veio realmente da QuettaCode, enviamos um header X-Quetta-Signature. Essa assinatura é um HMAC-SHA256 do corpo da requisição usando sua chave secreta de Webhook (Webhook Secret).

Validação (Exemplo em Node.js):

const crypto = require('crypto');
const signature = req.headers['x-quetta-signature'];
const hash = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET)
                   .update(JSON.stringify(req.body))
                   .digest('hex');

if (hash !== signature) {
  // Rejeitar requisição
}

Retentativas (Retry)

Se sua URL retornar um status diferente de 2xx (ex: 500, 404) ou der timeout, a QuettaCode tentará reenviar o evento automaticamente com backoff exponencial (ex: 1m, 5m, 15m, 1h...).