Webhooks (Nequi)

Nequi notifica los cambios de estado a nuestro gateway. Nosotros recibimos, persistimos, actualizamos la transacción y el balance, y enviamos el evento a tu webhookUrl configurada, con reintentos. Puedes configurar una URL distinta por proveedor (NEQUI / BREB).

Eventos

El tipo de evento viaja en el header X-Webhook-Event, no en el body.

Evento	Cuándo
`payin.completed`	El cobro (push o QR) fue aprobado y liquidado
`payin.failed`	El cobro fue rechazado o falló
`payin.expired`	El cobro venció sin pago
`payin.reversed`	Un cobro completado fue reversado
`payout.completed`	La dispersión se completó
`payout.failed`	La dispersión falló
`payout.expired`	La dispersión venció sin confirmación del proveedor
`payout.reversed`	Una dispersión fue reversada

Payload

payin.completed / payin.failed / payout.completed / payout.failed:

POST /tu-webhook HTTP/1.1
Content-Type: application/json
X-Webhook-Event: payin.completed
X-Webhook-Timestamp: 2026-06-01T10:05:00.000Z
X-Webhook-Signature: sha256=...

{
  "txId": "3f9f0c2a8b414f0e9a1d2c3b4a5e6f70",
  "reference": "orden-8842",
  "type": "PAYIN",
  "status": "COMPLETED",
  "amount": 50000,
  "currency": "COP",
  "feeCharged": 1500,
  "netAmount": 48500,
  "updatedAt": "2026-06-01T10:05:00.000Z"
}

Campo	Descripción
`txId`	ID de la transacción (coincide con el de la creación)
`reference`	El valor que enviaste al crear la transacción, o `null` si no enviaste ninguno
`type`	`PAYIN` o `PAYOUT`
`status`	`COMPLETED` o `FAILED`
`amount`	Monto en pesos COP
`feeCharged`	Fee cobrado en pesos COP (`0` si falló)
`netAmount`	Monto neto acreditado — solo en `payin.completed`

payin.expired / payout.expired:

{
  "txId": "9c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
  "reference": null,
  "type": "PAYIN",
  "status": "EXPIRED",
  "amount": 50000,
  "currency": "COP",
  "failureReason": "Cobro Nequi expirado sin pago",
  "expiredAt": "2026-06-01T10:45:00.000Z"
}

Firma del webhook

Los webhooks que te enviamos van firmados con HMAC-SHA256 usando la Clave que registraste para NEQUI. Verifica X-Webhook-Signature con tu Clave antes de confiar en el payload. Ver Verificación de firma.

Sandbox

En modo sandbox el gateway simula el desenlace automáticamente: al crear una transacción, esta pasa a COMPLETED y recibes el webhook de inmediato con un campo extra:

{ "txId": "...", "reference": "orden-8842", "type": "PAYIN", "status": "COMPLETED", "amount": 50000, "currency": "COP", "feeCharged": 1500, "netAmount": 48500, "sandbox": true }