Saltar al contenido principal

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.

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.

Cada entrega es un sobre de evento en JSON:

{
  "id": "evt_...",
  "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 cuando el pago alcanza un estado final — incluso si el cliente cierra el navegador durante la redirección. Ú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.

GrupoEventos
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
Devolucionesrefund.succeeded, refund.failed, refund.pending
Suscripcionessubscription.activated, subscription.updated, subscription.canceled, subscription.paused, subscription.past_due, subscription.trialing, subscription.pending, subscription.expired

Reintentos​

Si tu servidor no responde 200 OK, MONEI lo vuelve a intentar, esperando cada vez más tras cada fallo. Son 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 larga te deja casi una semana laboral para arreglarla.

No son infinitos. Tras el último intento se abandona el evento, y los eventos nunca se guardan en cola para entregarlos más tarde.

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.

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.

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.