> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://academy.zrupay.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Cómo configurar Webhooks

# ¿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](https://academy.zrupay.com/es/article/clave-publica-y-clave-secreta-1ncrqys/).