Webhooks

Ripei notifica a tu sistema en tiempo real cuando tus clientes pagan. Configuras una URL HTTPS y Ripei le hace POST con el detalle de cada evento — sin importar el método de pago que haya usado el cliente (tarjeta, pago móvil, transferencia, domiciliación…).

Eventos

Evento	Cuándo se dispara
`payment.received`	Se registró y validó un pago contra una factura (una factura puede recibir varios pagos parciales).
`bill.paid`	Una factura quedó pagada por completo.
`webhook.test`	Evento sintético de prueba, disparado manualmente al validar la configuración.

Configuración

La configuración se hace desde el dashboard de tu empresa (sección Webhooks) o solicitándola al equipo de Ripei. Defines:

URL del receptor (HTTPS obligatorio).
Eventos a los que te suscribes.
Autenticación con la que Ripei firmará/autenticará sus llamadas a tu sistema:

Tipo	Cómo funciona
`NONE`	Sin header de autorización (solo para pruebas).
`BEARER_TOKEN`	Ripei envía `Authorization: Bearer <token que definas>`.
`BASIC_AUTH`	`Authorization: Basic base64(usuario:contraseña)`.
`HMAC_SHA256`	Recomendado. Ripei firma cada payload y envía la firma en `X-Ripei-Signature` (formato `t=<unix>,v1=<hex>`). Verificas computando HMAC-SHA256 de `"{t}.{body}"` con el secreto compartido.
`OAUTH_CLIENT_CREDENTIALS`	Ripei pide un access token a tu endpoint `/token` antes de cada envío y lo usa como Bearer.

Headers de cada entrega


X-Ripei-Event: bill.paid
X-Ripei-Idempotency-Key: wd_1a2b3c4d-…
Content-Type: application/json
User-Agent: Ripei-Webhooks/1.0

X-Ripei-Event identifica el tipo de evento — el body no lleva campo event.
X-Ripei-Idempotency-Key es única por entrega: si Ripei reintenta, la key se repite. Úsala para deduplicar en tu lado.

Payload

El body es plano. Si el cliente tiene metadata, sus llaves se aplanan al primer nivel del JSON — así recibes directamente tus identificadores internos.

`bill.paid`


{
  "idClienteERP": "CLI-00042",
  "bill": {
    "id": 9902,
    "amount": 25,
    "status": "PAID",
    "billingDate": "2026-08-15T00:00:00.000Z",
    "fullyPaidAt": "2026-08-10T14:22:05.000Z",
    "description": "Cargo por inscripción"
  },
  "payments": [
    {
      "id": 830,
      "amount": 25,
      "reference": "11111111",
      "validatedAt": "2026-08-10T14:22:05.000Z",
      "paymentMethodId": 19
    }
  ],
  "companyUser": { "id": 4275 }
}

`payment.received`


{
  "idClienteERP": "CLI-00042",
  "payment": {
    "id": 830,
    "amount": 25,
    "reference": "11111111",
    "validatedAt": "2026-08-10T14:22:05.000Z",
    "paymentMethodId": 19
  },
  "bill": { "id": 9902, "amount": 25, "status": "PAID", "billingDate": "…", "fullyPaidAt": "…", "description": "…" },
  "companyUser": { "id": 4275 }
}

En ambos ejemplos, idClienteERP proviene del metadata que enviaste al crear el cliente.

Campos extra fijos. Si tu sistema receptor exige claves adicionales en cada payload (ej. "pasarela": "Ripei"), el equipo de Ripei puede configurarlas para tu empresa — se agregan a todos los envíos automáticamente.

Respuesta esperada y reintentos

Responde HTTP 2xx para confirmar la recepción. El body de tu respuesta se guarda para diagnóstico pero no se procesa.
Ante 5xx o timeout (10 segundos), Ripei reintenta hasta 3 veces con backoff exponencial.
Ante 4xx, se considera rechazo definitivo y no se reintenta.
Si una entrega agota los reintentos, el equipo de Ripei recibe una alerta automática.

Diseña tu receptor idempotente: con X-Ripei-Idempotency-Key puedes descartar entregas duplicadas. Responde rápido (2xx inmediato) y procesa en background — el timeout es de 10 segundos.

Buenas prácticas

Usa HMAC_SHA256 y verifica la firma antes de procesar.
Deduplica por X-Ripei-Idempotency-Key.
Usa el metadata del cliente para mapear los eventos a tus registros internos sin llamadas adicionales.
Loguea el body completo de las primeras entregas mientras estabilizas la integración.