Recibir eventos de webhook

MONEI notifica a tu servidor cuando ocurre algo con un pago, una devolución o una suscripción — para que puedas completar pedidos, actualizar tu base de datos o enviar recibos sin tener que consultar continuamente. Hay dos formas de recibir estas notificaciones.

Webhooks de cuenta

Los webhooks de cuenta envían todos los eventos a los que te suscribas, de toda tu actividad. Configúralos en Panel → Configuración → Webhooks:

1. Añade una URL de destino del webhook — una URL https:// en tu servidor.
2. Selecciona los tipos de evento que quieres recibir.
3. Actívalo.

Diálogo Añadir un nuevo webhook en los ajustes del panel de MONEI, con la URL del endpoint y los eventos que se envían

Puedes añadir más de un destino — por ejemplo, uno para pagos y otro para suscripciones. Cada destino aparece con los eventos que recibe y si está activo. Haz clic en un destino para ver todos los eventos que MONEI le ha enviado — consulta Supervisar las entregas.

Página Webhooks en los ajustes del panel de MONEI, con los endpoints que MONEI notifica

Cada entrega es un sobre de evento en JSON:

{
  "id": "d0c3e5b8a7f24c1e9b6a2f0e8d7c4b3a",
  "type": "charge.succeeded",
  "object": {"id": "...", "status": "SUCCEEDED"}
}

Lee type para saber qué ha ocurrido, y object para obtener el recurso afectado (un pago, una devolución o una suscripción).

Callback de pago (callbackUrl)

Al crear un pago, puedes establecer un callbackUrl. MONEI envía entonces el objeto Payment directamente (no un sobre) a esa URL — incluso si el cliente cierra el navegador durante la redirección. Lo envía una sola vez: la primera vez que el pago se completa, falla, se autoriza o se cancela, o cuando se completa un payout. No lo envía cuando un pago caduca, y un pago autorizado que capturas más tarde no recibe un segundo callback: usa los webhooks de cuenta para seguir los cambios posteriores. Úsalo cuando solo te interese el resultado de un pago concreto.

Consulta Verificar firma para ver ejemplos listos para usar en Node, PHP y Python que gestionan el callback.

Tipos de evento

Un charge es un pago, así que los eventos charge.* reflejan el ciclo de vida del pago.

Grupo	Eventos
Pagos (charges)	charge.succeeded, charge.failed, charge.pending, charge.pending_processing, charge.authorized, charge.captured, charge.canceled, charge.expired, charge.refunded, charge.partially_refunded, charge.paid_out, charge.chargeback, charge.updated
Disputas	chargeback.created, chargeback.escalated, chargeback.representment_submitted, chargeback.under_review, chargeback.won, chargeback.lost, chargeback.expired, chargeback.closed, chargeback.updated
Liquidaciones (payouts)	settlement.completed, settlement.pending, settlement.suspended
Suscripciones	subscription.activated, subscription.updated, subscription.canceled, subscription.paused, subscription.past_due, subscription.trialing, subscription.pending, subscription.expired
Facturas de MONEI	account_invoice.paid, account_invoice.pending, account_invoice.unpaid, account_invoice.past_due

Una devolución no tiene evento propio: el pago al que pertenece informa charge.refunded, o charge.partially_refunded cuando queda parte del importe.

WebhookEventType describe qué significa cada evento.

Orden de entrega y duplicados

MONEI entrega cada evento al menos una vez, y sin garantizar el orden. Dos estados que cambian con segundos de diferencia pueden llegar al revés, y un reintento o un reenvío puede entregar un evento que tu servidor ya tiene. Ambos casos son poco frecuentes, pero tu código tiene que soportarlos:

• Haz tu código idempotente. Ignora un evento cuyo id ya hayas procesado.
• Fíjate en el pago, no en el orden de llegada. Lee status en la carga útil e ignora un evento que describa un estado que ya has superado. Cuando necesites certeza, consulta el pago.
• Suscríbete a los estados finales, como charge.succeeded y charge.failed. Cuantos menos eventos intermedios recibas, menos cambios casi simultáneos tendrás que ordenar.
• Rechaza lo que aún no puedas procesar. Responder con un estado distinto de 2xx le indica a MONEI que la entrega falló, así que el evento vuelve según el calendario de reintentos — hasta que se agoten esos intentos.

Para el resultado de un pago concreto, un callback de pago es la vía más directa: MONEI envía el objeto Payment al callbackUrl de ese pago y de ningún otro, así que no hay nada que ordenar.

Reintentos

MONEI espera hasta 60 segundos a que tu servidor responda. No sigue redirecciones, así que una respuesta 3xx cuenta como fallo.

Si tu servidor no responde con un estado 2xx, como 200 OK, MONEI lo vuelve a intentar, esperando cada vez más tras cada fallo. Un webhook de cuenta tiene 18 intentos repartidos a lo largo de unos tres días: primero con segundos de diferencia, luego minutos y después horas, con los últimos separados 11 horas. Una caída breve por tu parte no te cuesta nada, y una más larga aún te deja casi tres días para arreglarla. En modo de prueba solo hay 3 intentos, con segundos de diferencia, así que un destino de prueba roto aparece como fallido en pocos minutos.

No son infinitos. Tras el último intento se abandona el evento, y los eventos nunca se guardan en cola para entregarlos más tarde. Aun así, puedes reenviarlo tú durante 30 días.

Un destino solo se desactiva tras siete días fallando sin ningún acierto de por medio. Una sola entrega correcta en cualquier momento reinicia ese contador, así que un destino no se apaga por un problema pasajero. Cuando llega a desactivarse, MONEI avisa por correo a los administradores de tu cuenta y no le llega nada hasta que lo reactives en Panel → Configuración → Webhooks.

Un callback de pago tiene su propio calendario: unos 30 intentos, con una hora de diferencia, a lo largo de unas 29 horas. Los callbacks no aparecen en el registro de entregas y no puedes reenviarlos. MONEI firma el callback una sola vez, así que cada reintento lleva la misma marca de tiempo en la cabecera MONEI-Signature. Si rechazas marcas de tiempo antiguas, ten en cuenta que un reintento puede llegar horas después del primer intento.

Así que no des la entrega por garantizada. Recupera lo que puedas haberte perdido consultando el pago en lugar de esperar un webhook que quizá nunca llegue.

Supervisar las entregas

Haz clic en un destino en Panel → Configuración → Webhooks para abrir su página:

• Endpoint — la URL, los tipos de evento y si el destino está activo, con Editar y Borrar.
• Últimos 30 días — cuántas entregas hizo MONEI cada día y cuántas fallaron, y lo rápido que respondió tu servidor, de media y en el caso más lento.
• Entregas de eventos — todos los eventos que MONEI ha enviado a este destino, del más reciente al más antiguo. Fíltralos por estado o busca un id. de evento.

Página de un endpoint de webhook en el panel de MONEI, con los datos del endpoint, los gráficos de entregas y tiempo de respuesta de los últimos 30 días y el registro de entregas de eventos

El modo de prueba y el modo real tienen destinos distintos, así que la página solo muestra las entregas del modo en el que estás. El registro cubre solo los webhooks de cuenta, no el callbackUrl de cada pago.

Estados de entrega

MONEI guarda una entrega por cada evento y destino, y la actualiza tras cada intento. La columna Intentos del registro los cuenta.

Estado	Significado
Entregado	Tu servidor respondió con un estado 2xx.
Pendiente	MONEI aún no la ha enviado.
Reintentando	Al menos un intento falló, y MONEI lo volverá a intentar.
Error	Todos los intentos fallaron, o MONEI no pudo enviarla (por ejemplo, el destino estaba desactivado). MONEI no lo vuelve a intentar, pero puedes reenviarla.

Consultar una entrega

Haz clic en una entrega para abrir sus detalles: el código de respuesta que devolvió tu servidor, cuánto tardó, cuándo lo intentó MONEI por última vez y cuándo lo volverá a intentar. Debajo están la Respuesta que envió tu servidor y la Solicitud que envió MONEI, que es la carga útil exacta del evento. Cuando una entrega falla, el cuerpo de la respuesta suele contener el error que produjo tu código.

Diálogo Detalles de entrega en el panel de MONEI, de una entrega que se está reintentando: el código y el cuerpo de respuesta de tu servidor, el siguiente reintento y la solicitud que envió MONEI

MONEI guarda las entregas durante 30 días, y los gráficos cubren el mismo periodo.

Reenviar una entrega

Cuando hayas corregido tu código, haz clic en Reenviar en los detalles de la entrega para enviar el evento de nuevo. MONEI envía la misma carga útil con el mismo id de evento, y la vuelve a firmar con una nueva marca de tiempo en la cabecera MONEI-Signature.

El reenvío es una entrega nueva en el registro, con sus propios reintentos. No detiene los reintentos de la entrega original, así que tu servidor puede recibir el mismo evento dos veces. Descarta los duplicados por el id del evento, nunca por la firma, que cambia en cada intento.

Reenviar no está disponible cuando:

• el destino está desactivado — actívalo primero;
• el evento era demasiado grande para que MONEI lo guardara completo.

Entregas en la API

Los mismos datos están en la API GraphQL. Lista las entregas con webhookDeliveries, consulta una con los cuerpos de la solicitud y la respuesta con webhookDelivery, obtén las cifras diarias de los gráficos con webhookDeliveryStats y reenvía con resendWebhookDelivery. Una entrega reenviada tiene source: MANUAL.

Verifica cada solicitud

Cada webhook y callback incluye una cabecera MONEI-Signature — una firma -SHA256 calculada con tu clave de API. Verifica siempre la firma antes de confiar en la carga útil y responde con un estado 200 para confirmar la recepción.

nota

Si eres socio de MONEI Connect, configura los webhooks en el Partner Dashboard — consulta MONEI Connect para desarrolladores.