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.charge.created	QR Code generado (cash-in pendiente)
pix.charge.paid	PIX recibido en la cuenta (cash-in confirmado)
pix.charge.expired	QR Code expirado sin pago
pix.payout.created	Transferencia PIX creada (cash-out)
pix.payout.confirmed	Transferencia PIX enviada con exito
pix.payout.failed	Transferencia PIX fallida
pix.payout.returned	Transferencia PIX devuelta por el destinatario
pix.refund.requested	Solicitud de devolucion MED recibida del BACEN
pix.refund.completed	Devolucion MED procesada
pix.return.received	Devolucion PIX recibida
webhook.test	Evento de prueba para validar la URL

Seguridad

Cada notificacion incluye headers de seguridad para validacion:

Header	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.charge.paid)

SHA256 en webhooks vs SHA512 en la API

La API usa HMAC-SHA512 para autenticar solicitudes que usted envia. Los webhooks enviados por Owem Pay usan HMAC-SHA256 en la firma X-Owem-Signature. Son algoritmos diferentes -- cada uno en su contexto.

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.

External ID en los Webhooks

Cuando una transaccion fue creada con external_id, ese campo se incluye en el payload del webhook dentro del objeto data. Uselo para correlacionar el evento con el pedido en su sistema sin necesidad de hacer una consulta adicional.

Requisitos del Endpoint

• La URL debe usar HTTPS (a menos que allow_insecure: true en el registro)
• Debe responder con estado 2xx en hasta 5 segundos
• El body de la respuesta es ignorado

Proximos Pasos

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