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.charge.created	QR code gerado
pix.charge.paid	PIX recebido e liquidado
pix.charge.expired	QR code expirado (24h)
pix.payout.processing	PIX enviado, aguardando confirmacao
pix.payout.confirmed	PIX enviado e confirmado
pix.payout.failed	PIX enviado rejeitado
pix.payout.returned	PIX enviado devolvido
pix.refund.requested	MED recebido, fundos bloqueados
pix.refund.completed	MED finalizado
pix.return.received	Devolucao PIX recebida (credito)
webhook.test	Teste manual

Seguranca

Cada notificacao inclui headers de seguranca para validacao:

Header	Descricao
X-Owem-Signature	Assinatura HMAC-SHA256 do payload
X-Owem-Timestamp	Unix timestamp em segundos do envio
X-Owem-Event-Id	ID unico do evento (para deduplicacao)
X-Owem-Event-Type	Tipo do evento (ex: pix.charge.paid)

SHA256 nos webhooks vs SHA512 na API

A API usa HMAC-SHA512 para autenticar requisicoes que voce envia. Os webhooks enviados pela Owem Pay usam HMAC-SHA256 na assinatura X-Owem-Signature. Sao algoritmos diferentes -- cada um no seu contexto.

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) {
  // timestamp is unix seconds (e.g., 1712160000)
  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 processa-lo sem duplicar efeitos.

External ID nos Webhooks

Quando uma transacao foi criada com external_id, esse campo e incluido no payload do webhook dentro do objeto data. Use-o para correlacionar o evento com o pedido no seu sistema sem precisar fazer uma consulta adicional.

Requisitos do Endpoint

• A URL deve usar HTTPS (a menos que allow_insecure: true no cadastro)
• 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