Webhooks

Webhooks permitem que você receba notificações em tempo real quando eventos ocorrem na sua conta WhatsApp, como novas mensagens, atualizações de status e mudanças de conexão.

Como Funciona

Quando um evento ocorre, a Oxenty API envia um POST request para a URL configurada com os dados do evento.

Configurando um Webhook

Via Dashboard

Acesse oxenty.api.br/login
Crie/edite uma sessão
Configure:

Webhook URL: Endpoint que receberá os eventos
Webhook Events: Quais eventos deseja receber

Via API

Webhooks são configurados por sessão.

Criar sessão já com webhook

curl -X POST "https://api.oxenty.api.br/api/sessions" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "minha-sessao",
    "webhookUrl": "https://seu-servidor.com/webhook",
    "webhookEvents": [
      "message.received",
      "message.sent",
      "message.delivered",
      "message.read",
      "session.connected",
      "session.disconnected"
    ]
  }'

Atualizar webhook de uma sessão existente

curl -X PUT "https://api.oxenty.api.br/api/sessions/{sessionId}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://seu-servidor.com/webhook",
    "webhookEvents": [
      "message.received",
      "message.sent",
      "session.status_changed"
    ]
  }'

Resposta:

{
  "id": "sess_abc123",
  "name": "minha-sessao",
  "status": "DISCONNECTED",
  "webhookUrl": "https://seu-servidor.com/webhook",
  "webhookEvents": ["message.received", "message.sent", "..."],
  "webhookSecret": "whsec_xxxxxxxxxxxxxxxx",
  "hasWebhook": true
}

Guarde o webhookSecret em local seguro. Ele é usado para validar a autenticidade dos webhooks.

Eventos Disponíveis

Mensagens

Evento	Descrição
`message.received`	Nova mensagem recebida
`message.sent`	Mensagem enviada com sucesso
`message.delivered`	Mensagem entregue
`message.read`	Mensagem lida
`message.failed`	Falha ao enviar mensagem
`message.revoked`	Mensagem apagada pelo remetente

Sessões

Evento	Descrição
`session.connected`	Sessão conectou ao WhatsApp
`session.disconnected`	Sessão desconectou
`session.qr_code`	QR Code disponível
`session.qr_updated`	QR Code atualizado/rotacionado
`session.status_changed`	Mudança de status da sessão

Grupos

Evento	Descrição
`group.created`	Grupo criado
`group.participant.added`	Participante adicionado
`group.participant.removed`	Participante removido
`group.updated`	Metadados do grupo atualizados

Contatos

Evento	Descrição
`contact.updated`	Dados do contato atualizados
`presence.update`	Status online/offline do contato
`presence.updated`	Atualização de presença (variação)

Payload do Webhook

Todos os webhooks seguem este formato:

{
  "id": "evt_xyz789",
  "type": "message.received",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "sessionId": "sess_abc123",
  "data": {
    // Dados específicos do evento
  }
}

Exemplo: message.received

{
  "id": "evt_xyz789",
  "type": "message.received",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "sessionId": "sess_abc123",
  "data": {
    "messageId": "msg_123",
    "from": "5511999999999@s.whatsapp.net",
    "fromName": "João Silva",
    "type": "text",
    "text": "Olá, tudo bem?",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "isGroup": false
  }
}

Exemplo: message.status

{
  "id": "evt_abc456",
  "type": "message.status",
  "timestamp": "2024-01-15T10:31:00.000Z",
  "sessionId": "sess_abc123",
  "data": {
    "messageId": "msg_456",
    "to": "5511888888888@s.whatsapp.net",
    "status": "read",
    "timestamp": "2024-01-15T10:31:00.000Z"
  }
}

Exemplo: session.disconnected

{
  "id": "evt_def789",
  "type": "session.disconnected",
  "timestamp": "2024-01-15T10:35:00.000Z",
  "sessionId": "sess_abc123",
  "data": {
    "reason": "logged_out",
    "message": "Usuário deslogou do WhatsApp Web"
  }
}

Validando Webhooks

Para garantir que o webhook veio da Oxenty API, valide a assinatura:

Header de Assinatura

X-Oxenty-Signature: sha256=abc123...
X-Oxenty-Timestamp: 1704067200

Validação em Node.js

import crypto from 'crypto';

function validateWebhook(
  payload: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  const receivedSignature = signature.replace('sha256=', '');
  
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(receivedSignature)
  );
}

// Uso no Express
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-oxenty-signature'] as string;
  const timestamp = req.headers['x-oxenty-timestamp'] as string;
  const payload = req.body.toString();
  
  if (!validateWebhook(payload, signature, timestamp, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  // Processar evento...
  
  res.status(200).send('OK');
});

Validação em Python

import hmac
import hashlib
from flask import Flask, request

app = Flask(__name__)
WEBHOOK_SECRET = 'whsec_xxxxxxxx'

def validate_webhook(payload, signature, timestamp, secret):
    signed_payload = f"{timestamp}.{payload}"
    expected_signature = hmac.new(
        secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    received_signature = signature.replace('sha256=', '')
    
    return hmac.compare_digest(expected_signature, received_signature)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Oxenty-Signature')
    timestamp = request.headers.get('X-Oxenty-Timestamp')
    payload = request.get_data(as_text=True)
    
    if not validate_webhook(payload, signature, timestamp, WEBHOOK_SECRET):
        return 'Invalid signature', 401
    
    event = request.get_json()
    # Processar evento...
    
    return 'OK', 200

Retries e Falhas

Se seu endpoint retornar erro (status >= 400) ou timeout, a Oxenty API fará retries automáticos:

Tentativa	Delay
1	Imediato
2	1 minuto
3	5 minutos
4	30 minutos
5	2 horas

Após 5 falhas consecutivas, o webhook é marcado como inativo e você receberá um email de notificação.

Responda com 200 OK o mais rápido possível. Processe eventos de forma assíncrona para evitar timeouts.

Boas Práticas

Responda rapidamente

Retorne 200 OK imediatamente e processe o evento de forma assíncrona (usando filas como Redis, RabbitMQ, etc.).

Sempre valide a assinatura

Nunca processe webhooks sem validar a assinatura para evitar ataques.

Implemente idempotência

Use o id do evento para evitar processar o mesmo evento duas vezes (pode haver retries).

Use HTTPS

Sempre use URLs HTTPS para receber webhooks. HTTP não é aceito em produção.

Testando Webhooks

Teste rápido

Configure webhookUrl em uma sessão (via POST /sessions ou PUT /sessions/{id})
Dispare um evento (ex.: enviar mensagem via POST /messages/text)
Verifique se seu endpoint recebeu o payload

Ferramentas Úteis

webhook.site - Endpoint temporário para testes
ngrok - Expor localhost para a internet
Hookdeck - Proxy e debug de webhooks

Gerenciando Webhooks

Listar configurações

curl -X GET "https://api.oxenty.api.br/api/sessions?page=1&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Atualizar Webhook (por sessão)

curl -X PUT "https://api.oxenty.api.br/api/sessions/sess_abc123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://seu-servidor.com/webhook",
    "webhookEvents": ["message.received"],
    "regenerateSecret": true
  }'

Desativar Webhook

curl -X PUT "https://api.oxenty.api.br/api/sessions/sess_abc123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": null,
    "webhookEvents": []
  }'

Introdução

Guias

Como Funciona

Configurando um Webhook

Via Dashboard

Via API

Criar sessão já com webhook

Atualizar webhook de uma sessão existente

Eventos Disponíveis

Mensagens

Sessões

Grupos

Contatos

Payload do Webhook

Exemplo: message.received

Exemplo: message.status

Exemplo: session.disconnected

Validando Webhooks

Header de Assinatura

Validação em Node.js

Validação em Python

Retries e Falhas

Boas Práticas

Testando Webhooks

Teste rápido

Ferramentas Úteis

Gerenciando Webhooks

Listar configurações

Atualizar Webhook (por sessão)

Desativar Webhook

​Como Funciona

​Configurando um Webhook

​Via Dashboard

​Via API

​Criar sessão já com webhook

​Atualizar webhook de uma sessão existente

​Eventos Disponíveis

​Mensagens

​Sessões

​Grupos

​Contatos

​Payload do Webhook

​Exemplo: message.received

​Exemplo: message.status

​Exemplo: session.disconnected

​Validando Webhooks

​Header de Assinatura

​Validação em Node.js

​Validação em Python

​Retries e Falhas

​Boas Práticas

​Testando Webhooks

​Teste rápido

​Ferramentas Úteis

​Gerenciando Webhooks

​Listar configurações

​Atualizar Webhook (por sessão)

​Desativar Webhook

Como Funciona

Configurando um Webhook

Via Dashboard

Via API

Criar sessão já com webhook

Atualizar webhook de uma sessão existente

Eventos Disponíveis

Mensagens

Sessões

Grupos

Contatos

Payload do Webhook

Exemplo: message.received

Exemplo: message.status

Exemplo: session.disconnected

Validando Webhooks

Header de Assinatura

Validação em Node.js

Validação em Python

Retries e Falhas

Boas Práticas

Testando Webhooks

Teste rápido

Ferramentas Úteis

Gerenciando Webhooks

Listar configurações

Atualizar Webhook (por sessão)

Desativar Webhook