¿Qué es un Webhook?

Un webhook es un endpoint HTTP de tu servidor al que Zru envía notificaciones automáticas cuando se producen eventos en una transacción: pago confirmado, suscripción cancelada, autorización cargada, etc.

A diferencia del campo notify_url que se especifica al crear una transacción por API (que afecta solo a esa transacción), los webhooks configurados aquí son globales para el entorno: reciben notificaciones de todas las transacciones del entorno sin necesidad de configurar la URL una por una.

Webhooks vs Notificaciones

Conviene distinguir dos conceptos relacionados pero distintos en el panel de Zru:

• Webhooks: la configuración del endpoint. Aquí defines a qué URL enviar las notificaciones.
• Notificaciones (pestaña separada): los eventos enviados a esos endpoints. Cada notificación es un registro histórico con la solicitud que mandó Zru y la respuesta que devolvió tu servidor.

Dicho de otra forma: configura un webhook una vez, y empezarás a ver notificaciones en la pestaña Notificaciones cada vez que ocurra un evento.

Cómo acceder a Webhooks

• En el panel, asegúrate de estar en el entorno donde quieres configurar el webhook.
• Ve a Desarrolladores en el menú lateral.
• Haz clic en la pestaña "Webhooks" de la barra horizontal.

Cómo crear un Webhook

• Haz clic en el botón "Añadir Webhook" arriba a la derecha.
• Se abrirá un modal con estos campos:
• • Nombre: una descripción para identificar el webhook (por ejemplo: "Notificaciones a CRM").
  • URL: el endpoint HTTPS de tu servidor que recibirá las notificaciones.
  • Tipos de notificación: elige qué eventos quieres recibir. Están agrupados en nueve categorías que puedes desplegar: Transacciones, Suscripciones, Autorizaciones, Ventas, Transferencias, Clientes, Wallets, IBAN y Checkout.
  • Habilitado: toggle para activar o desactivar el webhook al crearlo.
• Haz clic en "Crear".

🧐 Cada categoría muestra un contador con los tipos que llevas seleccionados sobre el total, y tiene un Seleccionar todo para marcarlos de golpe.

🧐 Junto al nombre de cada evento verás su identificador técnico (por ejemplo transaction_confirmation_error). Es el valor que recibirás en la notificación, así que te sirve para programar tu integración.

✋ Tienes que elegir al menos un tipo de notificación para poder crear el webhook.

Acciones disponibles sobre los Webhooks

Una vez creado, el webhook aparece en el listado con su Nombre, su URL, el Tipo (los identificadores de los eventos a los que está suscrito) y si está Habilitado. Desde la cabecera puedes:

• Filtrar por estado con el selector "Todos los estados" (Habilitado / Deshabilitado).
• Exportar CSV del listado completo.

Recomendaciones

• Usa siempre HTTPS para el endpoint. Las notificaciones contienen datos sensibles de transacciones.
• Mantén endpoints idempotentes: Zru puede reintentar el envío si tu servidor responde con error. Tu código debe estar preparado para procesar la misma notificación más de una vez sin efectos duplicados.
• Devuelve siempre códigos HTTP 2xx cuando proceses correctamente la notificación. Cualquier otro código se considera fallo y puede generar un reintento.
• Para depurar, usa la pestaña Notificaciones: cada entrada incluye la solicitud que envió Zru, el código de respuesta de tu servidor y la respuesta completa.

🧐 Las notificaciones se firman siempre con la Clave predeterminada del entorno. Puedes leer más en esta guía.

Actualizado el: 11/08/2026