Webhooks e Integracoes

8.1 O que sao Webhooks

Webhooks permitem que o Voki envie notificacoes automaticas para seus sistemas externos quando eventos especificos ocorrem. Por exemplo, voce pode ser notificado quando uma chamada e concluida para registrar o atendimento no seu CRM.

Disponibilidade: Planos Avancado, Profissional e Enterprise.

8.2 Configurar um Webhook

1. Acesse "Configuracoes" > "Webhooks" no Painel do Gestor
2. Clique em "Novo Webhook"
3. Preencha:
   • URL: o endpoint do seu sistema que recebera as notificacoes (deve aceitar POST)
   • Eventos: selecione quais eventos deseja receber
   • Secret: chave secreta para validacao HMAC (gerada automaticamente ou definida por voce)
4. Clique em "Salvar"

8.3 Eventos Disponiveis

Evento	Descricao	Quando dispara
call.created	Chamada criada	Cliente entra na fila
call.assigned	Chamada atribuida	Atendente aceita a chamada
call.started	Chamada iniciada	Conexao WebRTC estabelecida
call.completed	Chamada completada	Chamada encerrada normalmente
call.missed	Chamada perdida	Cliente saiu da fila sem atendimento
customer.created	Cliente criado	Novo cliente cadastrado

8.4 Assinatura HMAC-SHA256

Cada notificacao enviada pelo Voki inclui uma assinatura HMAC-SHA256 no header X-Voki-Signature. Utilize esta assinatura para validar que a requisicao realmente veio do Voki:

# Exemplo de validacao em Python
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

// Exemplo de validacao em Node.js
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

8.5 Formato do Payload

Cada notificacao e enviada como uma requisicao HTTP POST com o seguinte formato:

{
  "event": "call.completed",
  "timestamp": "2026-02-20T14:30:00Z",
  "data": {
    "id": "uuid-da-chamada",
    "status": "completed",
    "duration_seconds": 342,
    "department_id": "uuid-do-departamento",
    "attendant_id": "uuid-do-atendente",
    "customer": {
      "name": "Nome do Cliente",
      "email": "cliente@email.com"
    }
  }
}

Headers enviados:

Content-Type: application/json
X-Voki-Signature: sha256=abc123...
X-Voki-Event: call.completed
X-Voki-Delivery: uuid-do-delivery

8.6 Deliveries e Reenvio

Cada tentativa de entrega de webhook e registrada. Na pagina de detalhes do webhook, voce pode:

• Visualizar o historico de entregas (deliveries)
• Ver o status de cada entrega (sucesso, falha, timeout)
• Reenviar uma entrega que falhou

8.7 Testar um Webhook

Para verificar se seu endpoint esta funcionando corretamente:

1. Na lista de webhooks, clique em "Testar" ao lado do webhook desejado
2. O sistema envia um payload de teste para o endpoint configurado
3. O resultado (sucesso ou erro) e exibido imediatamente

---