Webhooks -- Visao Geral

Webhooks permitem que sua aplicacao receba notificacoes em tempo real sobre eventos na plataforma Owem Pay. Quando um evento ocorre, a Owem Pay envia um HTTP POST para a URL cadastrada.

Como Funciona

1. Cadastre uma URL de webhook na sua conta
2. Quando um evento ocorrer (ex: PIX recebido), a Owem Pay envia um HTTP POST para sua URL
3. Sua aplicacao processa a notificacao e responde com status 2xx (200, 201 ou 204)

Eventos Disponiveis

Evento	Descricao
pix.received	PIX recebido na conta (cash-in confirmado)
pix.completed	Transferencia PIX enviada com sucesso (cash-out)
pix.failed	Transferencia PIX falhou
pix.refund	Devolucao PIX processada
pix.med	Notificacao MED recebida do BACEN

Seguranca

Cada notificacao inclui headers de seguranca para validacao:

Header	Descricao
X-Owem-Signature	Assinatura HMAC-SHA256 do payload
X-Owem-Timestamp	Timestamp do envio (ISO 8601)
X-Owem-Event-Id	ID unico do evento (para deduplicacao)
X-Owem-Event-Type	Tipo do evento (ex: pix.received)

Validando a Assinatura

Valide a assinatura para garantir que a notificacao foi enviada pela Owem Pay:

const crypto = require('crypto');

function validateWebhook(payload, timestamp, signature, secret) {
  const message = `${timestamp}.${payload}`;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Valide sempre

Nunca processe um webhook sem validar a assinatura. Isso protege contra requisicoes falsificadas.

Retry Policy

Se sua URL retornar um status diferente de 2xx, a Owem Pay realiza retentativas automaticas:

Tentativa	Intervalo
1a	Imediato
2a	1 minuto
3a	5 minutos
4a	30 minutos
5a	2 horas

Apos 5 tentativas sem sucesso, o evento e marcado como failed e nao sera reenviado automaticamente.

Idempotencia

Sua aplicacao deve ser idempotente: se receber o mesmo evento mais de uma vez (identificado pelo X-Owem-Event-Id), deve processá-lo sem duplicar efeitos.

Requisitos do Endpoint

• A URL deve usar HTTPS
• Deve responder com status 2xx em ate 5 segundos
• O body da resposta e ignorado

Proximos Passos

• Cadastrar Webhook -- criar, listar e remover webhooks
• Payloads dos Eventos -- exemplos de cada tipo de evento