Saltar al contenido principal
Los webhooks te notifican los eventos de tu cuenta en un callback HTTPS propio, firmados criptográficamente.

Crear una suscripción

  • event_type: uno de los eventos de la tabla siguiente, o * para todos.
  • callback_url: HTTPS obligatorio; se rechazan localhost e IPs privadas — para desarrollo local usa un túnel HTTPS.
  • secret: mínimo 16 caracteres; se usa para firmar cada entrega. Se almacena cifrado y no puede recuperarse. La suscripción recibe los eventos de tu cuenta. Puedes listar las suscripciones activas en cualquier momento:

Desactivar y reactivar una suscripción

Cuando un callback deja de usarse, desactívalo en vez de borrarlo (las suscripciones nunca se borran: quedan disabled y puedes reactivarlas cuando quieras):
Para reactivarla, el mismo llamado con { "status": "active" }.
  • El toggle rige lo futuro: una suscripción disabled deja de recibir eventos nuevos, pero las entregas ya encoladas siguen saliendo.
  • Es idempotente: repetir el estado vigente responde 200 sin cambiar nada.
  • Solo puedes tocar las suscripciones de tu cuenta: una suscripción de otra cuenta responde 404 (es indistinguible de una inexistente). | HTTP | error | Solución | |---|---|---| | 400 | invalid_status | El estado debe ser active o disabled | | 404 | not_found | La suscripción no existe o pertenece a otra cuenta |

Eventos

Payload de cada evento

En payout_status_changed, una actualización de screening técnico puede ser pending antes de cualquier débito. Las actualizaciones finales son completed o failed (con failed el débito ya fue reembolsado cuando recibes el evento). crypto_withdrawal_status_changed usa completed o failed. En payout_status_changed, status_code y status_message son el resultado normalizado que reporta el core. status_message puede venir vacío cuando el riel no entrega detalle adicional; se depura antes de la entrega y nunca contiene la identidad de un proveedor upstream.

Fallos terminales antes del débito

Si el screening falla antes del camino de débito, el evento puede ser terminal con status: "failed", predebit_failure: true y funds_debited: false; se omite receipt_url. Un fallo posterior al débito es distinto: el débito exacto se reembolsa antes del evento terminal. La plataforma también puede persistir revisiones de transición no terminales, por lo que un payout puede producir más de una entrega payout_status_changed; deduplica por X-Webhook-Event-ID y no crees otro payout.

Formato de entrega

Cada entrega es un POST JSON con estos headers:

Verificar las firmas

CBPay envía ambos headers de firma en cada entrega de webhook de plataforma. V1 sigue siendo válida y se continúa enviando, por lo que adoptar V2 no rompe la compatibilidad. Las integraciones nuevas deben verificar V2 primero y mantener el fallback a V1 mientras migran los receptores existentes.
Calcula el HMAC sobre el body crudo (bytes tal como llegan), no sobre el JSON re-serializado. Rechaza timestamps muy antiguos (> 5 minutos) para prevenir replay.

Reintentos e idempotencia

  • Tu endpoint debe responder 2xx dentro del timeout; cualquier otra respuesta se reintenta.
  • Hasta 5 intentos con backoff incremental: | Intento | 1 | 2 | 3 | 4 | 5 | |---|---|---|---|---|---| | Espera aprox. | inmediato | ~5s | ~20s | ~45s | ~80s |
  • Usa X-Webhook-Event-ID para deduplicar: el mismo evento puede llegar más de una vez (entregas at-least-once).
  • Si los 5 intentos fallan, el evento no se reenvía — recupera el estado con el GET del recurso (por eso ningún flujo debe depender SOLO del webhook).

Tu idempotency key vuelve en el payload

Cuando el evento viene de una operación que creaste con una idempotency_key (un payout, un payin con tarjeta, un retiro crypto, un envío desde wallet segregada, un refund…), el payload la trae de vuelta como idempotency_key — concilia la notificación contra tu propia referencia sin un GET extra.
  • Es opcional: presente solo cuando el request original traía una key no vacía, y omitida en caso contrario. Las operaciones creadas por la propia plataforma jamás exponen una key interna.
  • Eventos cubiertos: payout_status_changed, payin_credited, payin_settlement_scheduled, payin_expired, payin_refunded, crypto_withdrawal_status_changed y wallet_send_status_changed. transfer_received no la lleva.
  • El recurso payin también la devuelve en GET /v1/payins/{id}.

Buenas prácticas

  • Responde 200 de inmediato y procesa en background.
  • Registra el X-Webhook-Delivery-ID para trazabilidad.
  • No dependas solo de webhooks para estados críticos: puedes consultar el objeto por API en cualquier momento (GET /v1/payouts/{id}, etc.).

banking_virtual_iban_inbound

This event reports an inbound EUR transfer received by an owned virtual IBAN. The event is normalized before delivery; consumers should deduplicate by the event ID and fetch the banking operation or virtual account when they need the latest state. The event does not expose an upstream provider identity.

admin_announcement

Este evento account-scoped se emite cuando el broadcast aprobado por un administrador de la organización llega al canal de notificaciones de la cuenta. Es texto plano localizado, nunca HTML:
El evento solo se entrega a la cuenta seleccionada por la campaña. Puede recibirse mediante una suscripción webhook de cuenta o el event stream; deduplica las entregas por X-Webhook-Event-ID. dispute_status_changed: consulta la guía de disputas para payload y transiciones firmadas. Payins fiat locales: payin_credited lleva credit_asset/fiat_credited; payin_refunded lleva debited_asset/debited_amount.

Eventos de tickets de soporte

The following events are delivered to both account and organization audiences. Payloads contain identifiers and state only; message bodies, internal notes and attachment bytes never travel in an event. Verify the signature and deduplicate by event ID.

Payload de warroom_outreach

Este evento con alcance de cuenta es un aviso de seguridad de texto plano enviado por un god nombrado de plataforma. Contiene el asunto, el cuerpo después del aviso anti-phishing fijo, la etiqueta del remitente y la hora UTC de emisión:
El cuerpo es solo texto; el HTML se rechaza antes de entregar. Verifica la firma del webhook y deduplica por X-Webhook-Event-ID.
Última modificación el 8 de noviembre de 2026