Webhooks: eventos y firma
Al terminar esta página conocerás los cuatro eventos que Neat puede enviar a tu URL de webhook, la forma exacta de su cuerpo y cómo viene firmado.
Eventos
Sección titulada «Eventos»| Evento | Cuándo se envía |
|---|---|
payment.pending |
Un intento de cobro quedó registrado y todavía no tiene resultado definitivo. |
payment.succeeded |
Un cobro fue confirmado. |
payment.failed |
Un intento de cobro fue rechazado de forma definitiva. |
payment.refunded |
Un cobro confirmado fue devuelto por completo. |
Cuándo Neat notifica a tu comercio
Sección titulada «Cuándo Neat notifica a tu comercio»Neat encola un evento cuando registra el resultado de un cobro —succeeded, failed o pending— y
cuando se completa una cancelación (payment.refunded). Si tu comercio no tiene URL de webhook y
webhook_secret registrados, Neat no encola ningún evento ni lo guarda para después. Confirma tu
webhook antes de aceptar cobros reales, ver Pruebas y checklist.
Formato de la notificación
Sección titulada «Formato de la notificación»POST <tu URL de webhook>Content-Type: application/jsonNeat-Event-Id: evt_8f21c2a6b3e9Neat-Signature: t=1789427837,v1=f1f09c2b66d45b85429a5328428a138dd762b3c530ea08bc022aa4e7734bde7c{ "event_id": "evt_8f21c2a6b3e9", "type": "payment.succeeded", "api_version": "v1", "provider_id": "administradora_ejemplo", "occurred_at": "2026-09-14T23:17:17.894Z", "resource": { "type": "payment", "id": "pay_3ac4efd9f068", "version": 2, "session_id": "cs_6b1d0f4a92c7", "external_reference": "depto-301-2026-09" }, "data": { "payment_id": "pay_3ac4efd9f068", "version": 2, "status": "succeeded", "currency": "MXN", "principal_amount_minor": 125000, "payer_fee_minor": 3750, "payer_fee_tax_minor": 600, "provider_fee_minor": 0, "provider_fee_tax_minor": 0, "charged_amount_minor": 129350, "provider_net_amount_minor": 125000, "refunded_amount_minor": 0, "fee_bearer": "payer", "cancellation_state": "none", "paid_at": "2026-09-14T23:17:17.894Z", "category": "maintenance_fee", "concept": "Mensualidad de mantenimiento, septiembre 2026", "payee_name": "Administradora Ejemplo, S.A. de C.V." }}La firma del ejemplo se calculó con un webhook_secret de muestra
(whsec_demo_example_secret_do_not_use) sobre el JSON exactamente como se ve arriba, saltos de
línea e indentación incluidos: el HMAC es sobre bytes, así que reformatear el cuerpo cambia la firma.
Sirve para probar tu verificador copiando y pegando. El webhook_secret real es el que Neat te
entrega en el alta, y las entregas de verdad vienen en JSON compacto.
| Campo | Descripción |
|---|---|
event_id |
Identifica el hecho. No cambia entre reintentos del mismo evento. Igual al valor de Neat-Event-Id. |
type |
Uno de los cuatro eventos de la tabla anterior. |
api_version |
Siempre "v1". |
provider_id |
El provider_id de tu comercio. |
occurred_at |
Fecha del hecho. No cambia entre reintentos. |
resource.type |
Siempre "payment" en v1. |
resource.id, resource.version |
El payment_id afectado y su version en ese momento. |
resource.session_id |
La sesión de checkout del pago, el mismo valor que recibiste al crearla. null en un pago sin obligación, y también en una transferencia que salda una obligación cuya sesión el pagador había cancelado (ver abajo). |
resource.external_reference |
Tu propia referencia de la obligación, tal como la mandaste al crear la sesión. null en un pago sin obligación. |
data |
El pago completo, en la misma forma que payment dentro de una sesión, ver Importes y comisiones. |
Pagos sin obligación
Sección titulada «Pagos sin obligación»Un pagador puede transferir por SPEI a la CLABE de su unidad un monto que no coincide con ninguna
obligación abierta de esa unidad, o cuando no tiene ninguna abierta. Neat acredita igual el dinero y te
envía payment.succeeded, pero con resource.session_id y resource.external_reference en null,
porque ese pago no salda ninguna de tus obligaciones. En data, concept y category vienen vacíos.
No marques nada como pagado con ese evento: regístralo como dinero recibido sin aplicar y escríbenos
con el payment_id para aplicarlo.
Una transferencia por exactamente el monto de una obligación abierta de la unidad sí la salda, y su
evento trae tu referencia en resource.external_reference. Trae también la sesión si seguía abierta o
había vencido; si el pagador la canceló, resource.session_id viene en null. Usa
external_reference, y no session_id, para saber si el pago saldó una de tus obligaciones. Si la
unidad tiene varias abiertas por el mismo monto, salda la más antigua.
No hay un campo environment en el cuerpo del evento: el ambiente (prueba o producción) está
implícito en cuál webhook_secret verificó la firma.
Cada entrega trae dos cabeceras:
Neat-Event-Id: igual aevent_iden el cuerpo. Úsalo para deduplicar.Neat-Signature:t=<segundos unix>,v1=<hexadecimal>, un HMAC-SHA256 del texto"<t>.<cuerpo crudo>", con tuwebhook_secretcomo clave.
El detalle de cómo calcular y comparar la firma, con ejemplos en Node, Python y PHP, está en Verificar la firma. Nunca proceses un evento cuya firma no hayas verificado.
Qué hacer con cada evento
Sección titulada «Qué hacer con cada evento»| Evento | Acción esperada |
|---|---|
payment.pending |
No inicies otro cobro para la misma obligación mientras esté pendiente. |
payment.succeeded |
Marca la obligación como pagada para tu external_reference, que viene en resource.external_reference. Si viene null, ver Pagos sin obligación. |
payment.failed |
Registra el rechazo; la obligación sigue abierta para un nuevo intento del pagador. |
payment.refunded |
Registra la devolución y aplica tu propia política sobre la obligación, ver Importes y comisiones. |
Un evento puede llegar fuera de orden. Compara resource.version contra la versión que ya tengas
guardada para ese payment_id y no dejes que un evento antiguo sobreescriba un estado más nuevo, ver
Reintentos e idempotencia.