Webhooks (qué son, eventos canónicos)

Un webhook es un aviso que SPIDI te envía (POST) cuando algo pasa con una sesión. Es la forma fiable de enterarte de un pago: no dependes de que la persona vuelva a tu sitio.

Qué es vs cómo se maneja

Esta página explica qué son los webhooks (concepto). Para implementarlos (verificar firma, deduplicar, responder), ve a la guía → Manejar notificaciones.

Webhooks: qué son y los eventos canónicos

Anatomía de un aviso

SPIDI hace POST a tu webhook_url con un cuerpo JSON y estos headers:

• spidi-signature — sello HMAC-SHA256 del cuerpo crudo con el secreto de tu cuenta.
• spidi-timestamp — cuándo se generó.
• idempotency-key — identificador estable del envío, para deduplicar reintentos.

{ "event": "payment_session.paid", "data": { /* ... */ } }

Eventos del ciclo de pago

Los dos que verás en un pago típico:

Evento	Cuándo	Tiempo
payment_session.paid	El débito salió bien	leg 1
payment_session.accredited	El dinero se acreditó al beneficiario	leg 2

El leg 2 solo llega por webhook

paid confirma que el débito (leg 1) salió bien — no que el dinero ya está en manos del beneficiario. payment_session.accredited no se refleja en GET status (que se queda en paid): si no escuchas el webhook, no sabrás que el dinero se acreditó. → Transacción a dos tiempos.

Un evento de acreditación por cada parte del acuerdo

La acreditación (leg 2) puede llegar en varios eventos: el webhook recibe uno por cada transacción de crédito, es decir uno por cada parte especificada en el acuerdo. Un acuerdo sin split tiene una sola parte → un payment_session.accredited. Un acuerdo con split acredita a varios receptores → una acreditación por receptor más el cierre, todas a tu mismo webhook_url. → Split.

Entrega: reintentos e idempotencia

Si tu endpoint no responde 2xx a tiempo, SPIDI reintenta (hasta 3 veces) con el mismo idempotency-key. Por eso tu receptor debe deduplicar: procesar una vez aunque llegue varias.

Confirmar con SPIDI (no bloquea): el contrato (OpenAPI) nombra estos dos webhooks distinto al valor que trae el campo event del payload real — el simulador emite event: payment_session.paid / payment_session.accredited, que es lo que ves en esta página. El nombre oficial de estos eventos está por confirmar con SPIDI; hasta entonces, guíate por el event del payload, no por el nombre del webhook en el contrato. El detalle fino de la firma (spidi-signature, HMAC sobre el cuerpo crudo) también está en revisión. Se corrige en un solo lugar cuando llegue el dato oficial.

→ Manejar notificaciones · Usar el simulador