Webhooks -- Vision General

Los webhooks permiten que su aplicacion reciba notificaciones en tiempo real sobre eventos en la plataforma Owem Pay. Cuando ocurre un evento, Owem Pay envia un HTTP POST a la URL registrada.

Como Funciona

1. Registre una URL de webhook en su cuenta
2. Cuando ocurra un evento (ej: PIX recibido), Owem Pay envia un HTTP POST a su URL
3. Su aplicacion procesa la notificacion y responde con estado 2xx (200, 201 o 204)

Eventos Disponibles

Evento	Descripcion
pix.received	PIX recibido en la cuenta (cash-in confirmado)
pix.completed	Transferencia PIX enviada con exito (cash-out)
pix.failed	Transferencia PIX fallida
pix.refund	Devolucion PIX procesada
pix.med	Notificacion MED recibida del BACEN

Seguridad

Cada notificacion incluye encabezados de seguridad para validacion:

Encabezado	Descripcion
X-Owem-Signature	Firma HMAC-SHA256 del payload
X-Owem-Timestamp	Marca de tiempo del envio (ISO 8601)
X-Owem-Event-Id	ID unico del evento (para deduplicacion)
X-Owem-Event-Type	Tipo del evento (ej: pix.received)

Validando la Firma

Valide la firma para garantizar que la notificacion fue enviada por 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 siempre

Nunca procese un webhook sin validar la firma. Esto protege contra solicitudes falsificadas.

Politica de Reintentos

Si su URL retorna un estado diferente de 2xx, Owem Pay realiza reintentos automaticos:

Intento	Intervalo
1o	Inmediato
2o	1 minuto
3o	5 minutos
4o	30 minutos
5o	2 horas

Despues de 5 intentos sin exito, el evento se marca como failed y no sera reenviado automaticamente.

Idempotencia

Su aplicacion debe ser idempotente: si recibe el mismo evento mas de una vez (identificado por el X-Owem-Event-Id), debe procesarlo sin duplicar efectos.

Requisitos del Endpoint

• La URL debe usar HTTPS
• Debe responder con estado 2xx en un plazo de 5 segundos
• El body de la respuesta es ignorado

Siguientes Pasos

• Registrar Webhook -- crear, listar y eliminar webhooks
• Payloads de los Eventos -- ejemplos de cada tipo de evento