Eventos de webhook

Lo que Paygumi envía a tus endpoints. Para recibirlos y verificar la firma, sigue la guía de webhooks.

Webhook que Paygumi envía a tus endpoints

POSThttps://tu-endpoint.example/…

Paygumi hace POST a cada endpoint ACTIVE del entorno del evento suscrito a su tipo (o a *). Responde cualquier 2xx en menos de 10 s; otro código, timeout o error de conexión se reintenta a 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h (8 intentos, ≈ 45 h) y luego la entrega queda EXHAUSTED. No se siguen redirects. Tras 100 fallos seguidos durante 3 días el endpoint se deshabilita y se avisa por correo a los OWNER y ADMIN.

Tipos: los de WebhookEventType (sin *), más ping (prueba manual).

Cabeceras

Cabeceras del webhook
Parámetro	En	Tipo	Descripción
`Paygumi-Event-Id`obligatorio	cabecera	string	Id del evento (`evt_…`); igual en reintentos y reenvíos. Deduplica por él.
`Paygumi-Timestamp`obligatorio	cabecera	string	Segundos Unix del envío. Rechaza diferencias de más de 5 min. Ejemplo: `1793509212`
`Paygumi-Signature`obligatorio	cabecera	string	`v1=<hex(HMAC_SHA256(secret, timestamp + "." + body))>`; durante una rotación, `v1=<nuevo>,v1=<anterior>` (acepta si alguna coincide).

Cuerpo (`WebhookEnvelope`)

Cuerpo de todo webhook. Firmado con Paygumi-Signature: v1=<hex(HMAC_SHA256(secret, Paygumi-Timestamp + "." + body))> (dos firmas separadas por coma durante una rotación) sobre los bytes exactos del cuerpo. Rechaza timestamps con más de 5 min de diferencia y deduplica por Paygumi-Event-Id (= id): la entrega es al menos una vez y sin orden garantizado (usa created_at).

Campos del cuerpo del webhook
Campo	Tipo	Descripción
`id`obligatorio	string	Ejemplo: `evt_01JB86R800ABCDEFGHJKMNPQRS`
`type`obligatorio	string	Ejemplo: `payment.declined`
`created_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`api_version`obligatorio	string	Ejemplo: `2026-10-01`
`livemode`obligatorio	boolean	`true` en producción.
`initiated_by`obligatorio	string	Valores: `system,` `tenant_api,` `dashboard,` `customer_portal,` `payment_link`
`test`	boolean	Solo en los envíos de prueba (`true`).
`data`obligatorio	object	Estado completo al momento del evento (estados en minúsculas). Trae `subscription` en los eventos `subscription.` y `payment.`, `charge` en `payment.`, `payment_method` en `payment_method.` y `checkout_session.completed`, y `checkout_session` en `checkout_session.*`. `cancellation` solo en `subscription.canceled` y `subscription.updated` de una cancelación hecha por el cliente en el portal.
`data.subscription`	object
`data.subscription.id`obligatorio	string	Ejemplo: `sub_01JB86R800ABCDEFGHJKMNPQRS`
`data.subscription.status`obligatorio	string	Valores: `trialing,` `active,` `past_due,` `unpaid,` `paused,` `canceled`
`data.subscription.access_status`obligatorio	string	Con este campo el tenant decide si da acceso. Valores: `granted,` `restricted,` `revoked`
`data.subscription.access_until`obligatorio	string (date-time) \| null
`data.subscription.cancel_at_period_end`	boolean
`data.subscription.canceled_at`	string (date-time) \| null
`data.subscription.customer`obligatorio	object
`data.subscription.customer.id`obligatorio	string
`data.subscription.customer.external_id`	string
`data.subscription.customer.name`	string
`data.subscription.plan`obligatorio	object
`data.subscription.plan.id`obligatorio	string
`data.subscription.plan.external_id`	string
`data.subscription.plan.name`	string
`data.subscription.previous_plan`	object
`data.subscription.previous_plan.id`obligatorio	string
`data.subscription.previous_plan.external_id`	string
`data.subscription.previous_plan.name`	string
`data.subscription.current_period`obligatorio	object
`data.subscription.current_period.start`obligatorio	string (date-time)	RFC 3339 en UTC.
`data.subscription.current_period.end`obligatorio	string (date-time)	RFC 3339 en UTC.
`data.subscription.trial_ends_at`	string (date-time) \| null
`data.subscription.pending_plan_change`	object \| null
`data.subscription.pending_plan_change.plan_id`	string
`data.subscription.pending_plan_change.effective_at`	string (date-time)	RFC 3339 en UTC.
`data.subscription.metadata`	object<string, string>
`data.charge`	object
`data.charge.id`obligatorio	string	Ejemplo: `chg_01JB86R800ABCDEFGHJKMNPQRS`
`data.charge.status`obligatorio	string	Valores: `scheduled,` `processing,` `pending,` `paid,` `failed,` `uncollectible,` `voided`
`data.charge.amount_in_cents`obligatorio	integer (int64)	Ejemplo: `4990000`
`data.charge.currency`obligatorio	string	Valores: `COP`
`data.charge.period`obligatorio	object
`data.charge.period.start`obligatorio	string (date-time)	RFC 3339 en UTC.
`data.charge.period.end`obligatorio	string (date-time)	RFC 3339 en UTC.
`data.charge.attempt`obligatorio	integer
`data.charge.failure_reason`	string \| null	Ejemplo: `INSUFFICIENT_FUNDS`
`data.charge.next_retry_at`	string (date-time) \| null
`data.charge.paid_at`	string (date-time) \| null
`data.payment_method`	object	Con `type` `NEQUI`: `brand` `NEQUI`, `last4` del celular y sin vencimiento. Con `BANCOLOMBIA_TRANSFER`: `brand` `BANCOLOMBIA_AHORROS` / `BANCOLOMBIA_CORRIENTE` / `BANCOLOMBIA`, `last4` de la cuenta y sin vencimiento. En `payment_method.invalidated`, `status: invalid`.
`data.payment_method.id`obligatorio	string	Ejemplo: `pm_01JB86R800ABCDEFGHJKMNPQRS`
`data.payment_method.status`obligatorio	string	Ejemplo: `active`
`data.payment_method.type`obligatorio	string	Valores: `CARD,` `NEQUI,` `BANCOLOMBIA_TRANSFER` Ejemplo: `CARD`
`data.payment_method.brand`	string	Ejemplo: `VISA`
`data.payment_method.last4`	string	Ejemplo: `4242`
`data.payment_method.exp_month`	integer
`data.payment_method.exp_year`	integer
`data.payment_method.customer`obligatorio	object
`data.payment_method.customer.id`obligatorio	string
`data.payment_method.customer.external_id`	string
`data.payment_method.customer.name`	string
`data.checkout_session`	object
`data.checkout_session.id`obligatorio	string	Ejemplo: `cs_01JB86R800ABCDEFGHJKMNPQRS`
`data.checkout_session.mode`obligatorio	string	Valores: `setup,` `subscription`
`data.checkout_session.status`obligatorio	string	Ejemplo: `completed`
`data.checkout_session.metadata`	object<string, string>
`data.cancellation`	object	Motivo y comentario del cliente al cancelar desde el portal (`initiated_by` `customer_portal`).
`data.cancellation.reason`	string \| null
`data.cancellation.comment`	string \| null

Tipos de evento

payment.approved
payment.pending
payment.declined
payment.uncollectible
subscription.created
subscription.activated
subscription.past_due
subscription.unpaid
subscription.paused
subscription.resumed
subscription.canceled
subscription.plan_changed
subscription.updated
subscription.access_changed
checkout_session.completed
checkout_session.expired
payment_method.added
payment_method.invalidated
ping

Cuándo se envía cada uno: catálogo de eventos.

Eventos de webhook

Webhook que Paygumi envía a tus endpoints

Cabeceras

Cuerpo (WebhookEnvelope)

Tipos de evento

Cuerpo (`WebhookEnvelope`)