Webhooks

Conceituacao

Webhooks permitem que voce receba notificacoes em tempo real quando eventos ocorrem na plataforma Ogmma. Em vez de fazer requisicoes periodicas (polling) para verificar se algo mudou, a Ogmma envia uma requisicao HTTP POST diretamente para a URL que voce configurar sempre que um evento relevante acontecer.

Isso permite que sua aplicacao reaja imediatamente a eventos como:

• Mensagem recebida de um contato
• Mensagem enviada confirmada pelo WhatsApp
• Mensagem entregue ou lida
• Conversa criada ou encerrada
• Canal conectado ou desconectado

Como Funciona

1. Voce registra um webhook com uma URL de destino e seleciona os eventos que deseja receber.
2. Quando um evento ocorre, a Ogmma envia um POST com o payload do evento para sua URL.
3. Sua aplicacao processa o payload e retorna um status HTTP 2xx para confirmar o recebimento.
4. Caso a entrega falhe, a Ogmma realiza tentativas automaticas de acordo com a politica de retry configurada.

Componentes de um Webhook

Componente	Descricao
URL	Endereco HTTPS para onde os eventos serao enviados. Apenas HTTPS e aceito.
Eventos	Lista de eventos que o webhook deve receber (ex: message.received, conversation.created).
Secret	Chave secreta usada para gerar a assinatura HMAC-SHA256 de cada payload.
Politica de Retry	Configuracao de tentativas automaticas em caso de falha (maxRetries, retryDelay).
Status	Ativo ou inativo. Webhooks inativos nao recebem eventos.

Eventos Disponiveis

Evento	Descricao
message.received	Mensagem recebida de um contato.
message.sent	Mensagem enviada via API confirmada pelo WhatsApp.
message.delivered	Mensagem entregue no dispositivo do destinatario (duplo check).
message.read	Mensagem lida pelo destinatario (checks azuis).
conversation.created	Nova conversa criada (primeira mensagem de um novo contato).
conversation.closed	Conversa encerrada (por atendente ou via API).
channel.connected	Canal WhatsApp conectado com sucesso.
channel.disconnected	Canal perdeu a conexao.
contact.created	Novo contato criado na instituicao.
contact.updated	Dados de um contato atualizados.
bulk.completed	Lote de envio em massa concluido com sucesso.
bulk.failed	Lote de envio em massa falhou ou foi cancelado.

Seguranca - Assinatura HMAC-SHA256

Todos os payloads enviados pela Ogmma sao assinados usando HMAC-SHA256 com o secret que voce definiu ao criar o webhook. A assinatura e enviada no header X-Ogmma-Signature.

Voce deve sempre verificar a assinatura antes de processar o payload para garantir que a requisicao realmente veio da Ogmma e nao foi adulterada.

Como a Assinatura e Gerada

1. A Ogmma serializa o payload do evento em JSON.
2. Gera o HMAC-SHA256 do JSON usando o secret do webhook.
3. Envia o resultado como hex no header X-Ogmma-Signature.

Exemplo de Verificacao em Node.js

const crypto = require('crypto');

function verificarAssinatura(payload, assinatura, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(digest, 'hex'),
    Buffer.from(assinatura, 'hex')
  );
}

// Uso em um endpoint Express
app.post('/webhook', (req, res) => {
  const assinatura = req.headers['x-ogmma-signature'];
  const secret = 'seu_secret_aqui';

  if (!verificarAssinatura(req.body, assinatura, secret)) {
    return res.status(401).json({ error: 'Assinatura invalida' });
  }

  // Processar o evento
  console.log('Evento recebido:', req.body.event);
  res.status(200).json({ ok: true });
});

Exemplo de Verificacao em Python

import hmac
import hashlib
import json

def verificar_assinatura(payload, assinatura, secret):
    digest = hmac.new(
        secret.encode('utf-8'),
        json.dumps(payload, separators=(',', ':')).encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(digest, assinatura)

# Uso em um endpoint Flask
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    assinatura = request.headers.get('X-Ogmma-Signature')
    secret = 'seu_secret_aqui'

    if not verificar_assinatura(request.json, assinatura, secret):
        return jsonify({'error': 'Assinatura invalida'}), 401

    # Processar o evento
    print('Evento recebido:', request.json['event'])
    return jsonify({'ok': True}), 200

Politica de Retry

Quando a entrega de um evento falha (sua URL retorna um status diferente de 2xx ou nao responde dentro do timeout), a Ogmma realiza tentativas automaticas:

Configuracao	Padrao	Descricao
maxRetries	5	Numero maximo de tentativas apos a primeira falha.
retryDelay	30000	Intervalo em milissegundos entre tentativas (30 segundos).

Desativacao Automatica

Para proteger a performance do sistema, webhooks sao desativados automaticamente apos 5 falhas consecutivas de entrega. Quando isso ocorre:

1. O webhook e marcado como active: false.
2. O campo consecutiveFailures atinge o limite.
3. Nenhum novo evento e enviado para esse webhook ate que seja reativado manualmente.

Para reativar, utilize o endpoint de atualizacao de webhook definindo active: true. O contador de falhas consecutivas sera resetado.

Dica

Monitore os logs de entrega do webhook via endpoint GET /api/webhooks/:id/logs para identificar problemas de conectividade antes que a desativacao automatica ocorra.

Importante

A URL do webhook deve utilizar HTTPS obrigatoriamente. URLs com HTTP serao rejeitadas na criacao e atualizacao do webhook.