Ir al contenido

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.

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.

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.

POST <tu URL de webhook>
Content-Type: application/json
Neat-Event-Id: evt_8f21c2a6b3e9
Neat-Signature: t=1789427837,v1=f1f09c2b66d45b85429a5328428a138dd762b3c530ea08bc022aa4e7734bde7c
payment.succeeded
{
"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.

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 a event_id en el cuerpo. Úsalo para deduplicar.
  • Neat-Signature: t=<segundos unix>,v1=<hexadecimal>, un HMAC-SHA256 del texto "<t>.<cuerpo crudo>", con tu webhook_secret como 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.

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.