Configurando el webhook

INFI envía una notificación HTTP POST a tu servidor cuando el estado de un cobro o retiro cambia. Puedes configurar hasta 6 URLs, cada una recibiendo categorías específicas de evento (o todo).

Diagrama

Cada URL recibe solo los eventos que filtra. Múltiples URLs pueden hacer match al mismo evento — todas reciben en paralelo.

Registro

En el panel de INFI, en Webhooks → Configuración:

Haz clic en Añadir webhook.
Indica la URL HTTPS (HTTP es rechazado — seguridad).
Elige qué recibe esa URL:
- Todos los eventos (catch-all).
- Seleccionar categorías: marca una o más entre cashin, cashout, refund, dispute, chargeback. Ver la lista completa en Eventos.
Marca activo y guarda.

Límite: 6 webhooks activos por cuenta. Para cambiar, quita uno antes de añadir otro.

Configuración legacy (URL única)

Las cuentas creadas antes de mayo/2026 pueden tener una URL legacy que recibe todos los eventos. Sigue funcionando como fallback si ninguno de los webhooks nuevos hace match al evento. Cuando configures URLs por categoría, considera quitar la legacy (botón “quitar” en el panel).

Ejemplo de configuración: 3 URLs por finalidad

URL 1: https://api.tuempresa.com/webhooks/infi-cashin
       → categoría "cashin"
       → recibe transaction.paid, transaction.failed, transaction.cancelled, transaction.expired

URL 2: https://api.tuempresa.com/webhooks/infi-cashout
       → categoría "cashout"
       → recibe todos los transfer.* (10 eventos)

URL 3: https://api.tuempresa.com/webhooks/infi-refund
       → categoría "refund" + "chargeback"
       → recibe transaction.refunded, transaction.partially_refunded, transaction.chargeback

Encabezados de la solicitud

Encabezado	Descripción
`Content-Type`	`application/json`
`X-Infi-Event`	Nombre canónico del evento (p.ej. `transaction.paid`).
`X-Infi-Timestamp`	Timestamp Unix en segundos, parte de la firma.
`X-Infi-Signature`	`sha256=<hex>` — HMAC-SHA256. Ver Firma.
`X-Infi-Event-Id`	ID único del evento (p.ej. `evt_1715000000000_abcdef12`). Igual entre URLs del fanout y reenvíos manuales — úsalo para dedup.

Cuerpo

{
  "event": "transaction.paid",
  "eventId": "evt_1715000000000_abcdef12",
  "transactionId": "Q4t9aV...",
  "status": "paid",
  "amountCents": 1000,
  "feeCents": 10,
  "netCents": 990,
  "paidAt": "2026-05-06T14:35:12.000Z",
  "timestamp": "1715000000"
}

Campo	Descripción
`event`	Nombre canónico del evento. Ver Eventos.
`eventId`	Identificador único del evento. Compartido entre URLs del fanout y reenvíos manuales — úsalo para dedup.
`transactionId`	Identifica la transacción.
`status`	Nuevo estado. Ver Estados.
`amountCents`, `feeCents`, `netCents`	Valores en centavos.
`paidAt`	ISO 8601 UTC cuando el estado final es `paid`; `null` en caso contrario.
`timestamp`	Eco del `X-Infi-Timestamp` para validación cruzada.

Entrega única — sin retry automático

INFI entrega el webhook en un único intento automático, con timeout de 8 segundos. Si tu aplicación no responde, el evento no se reenvía automáticamente. Estrategia recomendada:

Polling vía GET /v1/transactions/:id como fallback para recuperar estado.
Reenvío manual desde el panel — toda entrega queda registrada por 60 días y puede dispararse de nuevo. Ver Reenvío manual.

Respuesta esperada

Devuelve cualquier 2xx en hasta 8 segundos.
Haz el procesamiento pesado en background (worker, cola). Acusa recibo y encola.

Próximos

Eventos — lista completa.
Firma — cómo validar.
Reintento — estrategia de fallback.
Reenvío — cómo reenviar una entrega manualmente.

Consultar saldo Eventos