# Webhooks · Documentación de Pagos Express

> Recibe eventos payment.* y payment_link.* firmados con Pagos-Signature. Sobre del evento, verificación HMAC, reintentos y seguridad.

HTML: https://pagos.express/docs/webhooks
Texto para modelos: https://pagos.express/docs/webhooks.llms.txt
Índice de la documentación: https://pagos.express/docs

Registra un endpoint HTTPS en el dashboard y recibe un evento firmado cada vez que un pago o un enlace cambia. El registro y el secreto son del propietario; la API no los expone.

## Eventos
- `payment.succeeded`: la pasarela confirma el checkout como pagado (data.object: Payment).
- `payment.failed`: un método asíncrono falla tras el checkout.
- `payment.canceled`: la sesión expira o se cancela.
- `payment_link.paid`: el enlace queda liquidado (data.object: PaymentLink).
- `payment_link.disabled`: alguien desactiva el enlace.
- `payment.invoiced`: CFDI Express timbró la factura de un pago (data.object: PaymentInvoice).
- `payment.invoice_failed`: CFDI Express o el SAT rechazaron la factura; ve `failureReason`.
- `payment.invoice_cancelled`: el SAT confirmó la cancelación de la factura.
- `ping`: prueba desde el dashboard.

Sobre: `{ id: "evt_…", object: "event", type, livemode, createdAt, data: { object } }`. Payment y PaymentLink incluyen la `metadata` del enlace. Encabezados: `Pagos-Event-Id`, `Pagos-Event-Type`, `Pagos-Livemode`, `Pagos-Signature`. Los endpoints de pruebas y en vivo son independientes.

## Firma
`Pagos-Signature: t=<segundos unix>,v1=<hex>`; `v1` es HMAC-SHA256 con el secreto `whsec_…` sobre `"<t>.<cuerpo crudo>"`. Calcula sobre los bytes originales, compara en tiempo constante, rechaza marcas de más de cinco minutos. Responde 2xx en menos de 10 segundos y deduplica por `id`.

## Entrega y reintentos
- Los eventos se escriben en la misma transacción que el cambio de estado.
- Éxito es cualquier 2xx; las redirecciones cuentan como fallo.
- Reintentos: 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h (ocho intentos); después `failed`, reenviable desde el dashboard.
- A 100 fallos consecutivos el endpoint se desactiva.

## Seguridad
Secretos `whsec_` + 43 caracteres, mostrados una vez, rotables. URLs HTTPS públicas (sin credenciales, localhost, rangos privados ni .internal/.local). Hasta 10 endpoints por cuenta y modo. Timeout de 10 segundos.