Webhooks Salientes

Formato Standard Webhooks.

Headers en cada entrega

Header	Descripción
`webhook-id`	UUID único de esta entrega. Úsalo como `delivery_id` para idempotencia en tu receptor.
`webhook-timestamp`	UNIX timestamp del momento del envío.
`webhook-signature`	Firma de autenticidad. Formato: `v1,<base64(HMAC-SHA256)>`.
`webhook-event`	Tipo de evento (`payment.confirmed`, `payment.failed`, etc.).

Verificación de firma

mensaje_a_firmar = "{webhook-id}.{webhook-timestamp}.{raw_body_bytes}"
firma_esperada   = base64( HMAC-SHA256(mensaje_a_firmar, tu_webhook_secret) )

Compara con webhook-signature sin el prefijo v1,. Ejemplo en Python:

import base64
import hashlib
import hmac

def verificar_webhook_cucu(
    body: bytes,
    webhook_id: str,
    webhook_timestamp: str,
    webhook_signature: str,
    secret: str,
) -> bool:
    mensaje = f"{webhook_id}.{webhook_timestamp}.{body.decode()}"
    firma = base64.b64encode(
        hmac.new(secret.encode(), mensaje.encode(), hashlib.sha256).digest()
    ).decode()
    esperada = webhook_signature.removeprefix("v1,")
    return hmac.compare_digest(firma, esperada)

Ejemplo en Node.js:

const crypto = require('crypto');

function verificarWebhookCucu({ body, webhookId, webhookTimestamp, webhookSignature, secret }) {
  const mensaje = `${webhookId}.${webhookTimestamp}.${body}`;
  const firma = crypto
    .createHmac('sha256', secret)
    .update(mensaje)
    .digest('base64');
  const esperada = webhookSignature.replace('v1,', '');
  return crypto.timingSafeEqual(Buffer.from(firma), Buffer.from(esperada));
}

Eventos

`payment.confirmed`

Pago confirmado en la blockchain.

{
  "event": "payment.confirmed",
  "occurred_at": "2026-01-25T15:22:45Z",
  "charge_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CHG-20260125-00042",
  "provider": "cucu_pay",
  "amount": "50.00",
  "currency": "USDT",
  "status": "completed",
  "metadata": {
    "user_id": "usr_abc123",
    "plan": "pro",
    "invoice_id": "inv_0042"
  }
}

`payment.failed`

Pago detectado pero rechazado.

{
  "event": "payment.failed",
  "occurred_at": "2026-01-25T15:23:10Z",
  "charge_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CHG-20260125-00042",
  "provider": "cucu_pay",
  "amount": "50.00",
  "currency": "USDT",
  "status": "failed",
  "error": "amount_mismatch",
  "metadata": {}
}

`charge.expired`

Sin pago dentro del plazo.

{
  "event": "charge.expired",
  "occurred_at": "2026-01-25T15:30:00Z",
  "charge_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CHG-20260125-00042",
  "status": "expired",
  "metadata": {}
}

`charge.cancelled`

Cancelado vía POST /cancel.

{
  "event": "charge.cancelled",
  "occurred_at": "2026-01-25T15:20:00Z",
  "charge_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CHG-20260125-00042",
  "status": "cancelled",
  "metadata": {}
}

`reference_rate.updated` (opt-in)

Cambió el Tipo de Cambio Oficial del BCB (USD/BOB). No viene por defecto: pídelo en events al registrar el webhook. Al suscribirte recibes el valor vigente en el acto; después, uno por cada cambio. tc_oficial es el mismo objeto que devuelve GET /api/v1/tc/oficial. Si llega uno más nuevo antes de entregar el anterior, el anterior se descarta; no se reenvía.

{
  "event": "reference_rate.updated",
  "occurred_at": "2026-10-30T03:31:00+00:00",
  "reference": "BCB",
  "pair": "USD/BOB",
  "tc_oficial": {
    "valor": 12.11,
    "compra": 12.11,
    "venta": 12.11,
    "fecha": "2026-10-30",
    "vigencia_desde": "2026-10-30",
    "vigencia_hasta": "2026-10-30",
    "proxima": null,
    "proxima_publicacion": "2026-10-30T23:30:00-04:00",
    "desactualizado": false,
    "fuente": "Banco Central de Bolivia (bcb.gob.bo)"
  }
}

`webhook.test`

Sintético, de POST /merchants/me/webhook/test.

{
  "event": "webhook.test",
  "occurred_at": "2026-01-25T14:00:00Z",
  "merchant_id": "392b8825-18d3-404f-a029-2f11c8d14d32",
  "delivery_id": "d4e5f6a7-b8c9-0123-defa-456789abcdef"
}

Política de reintentos

Intento	Delay
1 (inmediato)	0s
2	~30s
3	~2min
4	~8min
5	~30min
6	~2h

Tras 6 fallos la entrega queda en failed. Solo 2xx cuenta como éxito (3xx y 5xx reintentan).

Referencia

Endpoints

Webhooks Salientes

Headers en cada entrega

Verificación de firma

Eventos

`payment.confirmed`

`payment.failed`

`charge.expired`

`charge.cancelled`

`reference_rate.updated` (opt-in)

`webhook.test`

Política de reintentos

​Headers en cada entrega

​Verificación de firma

​Eventos

​payment.confirmed

​payment.failed

​charge.expired

​charge.cancelled

​reference_rate.updated (opt-in)

​webhook.test

​Política de reintentos

Headers en cada entrega

Verificación de firma

Eventos

`payment.confirmed`

`payment.failed`

`charge.expired`

`charge.cancelled`

`reference_rate.updated` (opt-in)

`webhook.test`

Política de reintentos