Webhooks

Registrás una URL y te avisamos cada vez que te pagan un QR. No hace falta consultar el estado en un loop.

Registrar

curl -X POST https://qrsimple.cucu.bo/api/v1/webhook \
  -H "X-Api-Key: <tu_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://tu-sistema.com/webhooks/cucu"}'

{
  "url": "https://tu-sistema.com/webhooks/cucu",
  "secret": "whsec_...",
  "events": ["qr.paid"],
  "createdAt": "2026-09-22T20:15:00Z"
}

El secret sale una sola vez. Guardalo en tu gestor de secretos: después solo se puede rotar. La URL tiene que ser https y resolver a una dirección pública. Se valida al registrar y antes de cada entrega.

Método	Ruta	Qué hace
`POST`	`/api/v1/webhook`	Registra y devuelve el secreto
`GET`	`/api/v1/webhook`	Tu webhook, con el secreto enmascarado y su estado
`POST`	`/api/v1/webhook/rotate`	Secreto nuevo; el anterior sigue firmando durante la ventana de gracia
`POST`	`/api/v1/webhook/test`	Encola un evento de prueba (5 por minuto)
`DELETE`	`/api/v1/webhook`	Baja

El evento

{
  "event": "qr.paid",
  "occurredAt": "2026-09-22T20:42:48Z",
  "data": {
    "qrId": "36146199",
    "amount": "75.00",
    "currency": "BOB",
    "status": "PAID",
    "externalReference": "ORD-0871",
    "paidAt": "2026-09-22T20:42:48Z"
  }
}

amount viaja como string: es plata y un float pierde centavos. externalReference es el que mandaste al crear el QR.

Headers

Header	Qué trae
`webhook-id`	Id de la entrega. Usalo para no procesar dos veces el mismo aviso
`webhook-timestamp`	UNIX del envío
`webhook-signature`	`v1,<base64>` — puede traer más de una firma durante una rotación
`webhook-event`	`qr.paid`

Verificar la firma

Es Standard Webhooks: cualquier librería oficial sirve, y la misma verificación vale para la API de cripto de CUCU.

from standardwebhooks import Webhook

Webhook(secret).verify(raw_body, dict(request.headers))  # lanza si no valida

A mano:

firmado = f"{webhook-id}.{webhook-timestamp}.{cuerpo_crudo}"
firma   = base64(HMAC-SHA256(clave, firmado))

La clave HMAC son los bytes decodificados del secreto sin el prefijo whsec_, no su texto. Firmá sobre el cuerpo crudo, antes de parsearlo.

Reintentos

Respondé 2xx apenas recibas; procesá después.

6 intentos: al instante, 5 s, 30 s, 5 min, 30 min, 2 h.
15 segundos de timeout por intento.
Una redirección cuenta como fallo: registrá la URL final.
Si tu endpoint acumula fallos, se pausa un rato y se reanuda solo.

El mismo pago se puede entregar más de una vez (un timeout de tu lado, un reintento del nuestro). Deduplicá por webhook-id.

Si preferís preguntar vos

El webhook no reemplaza a consultar el estado: siempre podés preguntar por un qrId. Lo que ya no necesitás es preguntar en loop.

Información General

Endpoints

Webhooks

Webhooks

Registrar

El evento

Headers

Verificar la firma

Reintentos

Si preferís preguntar vos

​Webhooks

​Registrar

​El evento

​Headers

​Verificar la firma

​Reintentos

​Si preferís preguntar vos

Webhooks

Registrar

El evento

Headers

Verificar la firma

Reintentos

Si preferís preguntar vos