Administrar webhooks desde el panel
La sección Webhooks (/webhooks) te permite dar de alta suscripciones, revisarlas y consultar el historial de entregas de eventos hacia tus sistemas externos.
Si tu equipo de desarrollo necesita el catálogo completo de eventos, la especificación técnica de payloads, los alcances por Tenant o Comercio, y cómo verificar la firma de cada entrega, consulta Integrar webhooks dentro de la sección Documentación técnica.
Paso 1: entra a Webhooks
En el menú lateral, dentro del grupo Integraciones, entra a Webhooks.
Paso 2: revisa el panel general
Arriba de la pantalla encontrarás cuatro indicadores clave (KPIs):
- Suscripciones: Total de suscripciones registradas.
- Activas: Cantidad de suscripciones en estado activo recibiendo eventos.
- Entregas: Total acumulado de entregas de eventos procesadas.
- Entregas fallidas: Entregas que tuvieron error HTTP o timeout en el receptor y están en cola de reintento.
Paso 3: crea una suscripción
En el formulario de Nueva suscripción, completa los siguientes datos:
- Alcance / Comercio: Indica el comercio al que pertenece la suscripción (recibirá solo eventos de dicho comercio). Los usuarios administradores o integradores también pueden configurar suscripciones globales a nivel Tenant mediante la API.
- URL del endpoint: Dirección web donde tu servidor escuchará las notificaciones (debe utilizar protocolo seguro
https://en producción). - Secreto de firma: Clave compartida que se utilizará para calcular la firma HMAC-SHA256 de cada entrega. Cópialo y guárdalo en un lugar seguro, ya que por protección no podrá volver a consultarse en texto plano tras su creación.
- Tipos de eventos: Selecciona explícitamente los eventos que deseas recibir. Debes marcar al menos un evento; por diseño de seguridad fail-closed, una suscripción sin eventos asignados no recibirá notificaciones.
Eventos disponibles:
- Ventas:
sale.created,sale.approved,sale.declined,sale.cancelled,sale.refunded - Terminales:
terminal.created,terminal.updated - Comercios:
merchant.created,merchant.updated
Paso 4: consulta y administra las suscripciones
La tabla de Suscripciones muestra cada webhook configurado:
| Columna | Descripción |
|---|---|
| Subscription ID | Identificador único de la suscripción (ej. sub_...). |
| Alcance / Comercio | Comercio asignado o alcance global. |
| Endpoint | URL destino configurada. |
| Eventos | Lista de eventos suscritos. |
| Estado | Activa o Inactiva. |
| Creada | Fecha y hora de registro. |
| Acciones | Opciones para pausar/activar, rotar secreto o eliminar. |
Puedes filtrar la tabla por comercio o por estado. Desactivar una suscripción pausa el envío de nuevos eventos sin borrar el histórico de entregas.
Paso 5: consulta el historial de entregas
La tabla de Entregas registra cada intento de despacho de un evento:
| Columna | Descripción |
|---|---|
| Delivery ID | Identificador único de la entrega. |
| Subscription | ID de la suscripción receptora. |
| Evento | Tipo de evento despachado (ej. sale.approved). |
| Estado | Pendiente, En despacho, Entregado (2xx) o Fallido (con detalle del error HTTP o timeout). |
| Fecha / Intento | Marca de tiempo y contador de reintentos ejecutados. |
Si tu endpoint devuelve un error (código diferente a 2xx) o no responde dentro del tiempo límite, la plataforma reintenta el envío de forma automática con retroceso exponencial (1, 2, 4, 8 minutos... hasta 2 horas) hasta completar un máximo de 8 intentos.
Qué sigue
- Integrar webhooks — Catálogo técnico completo, formato del JSON y verificación de firma HMAC en Node.js y Python.
- Integrar Partner API — Conexión backend-to-backend para partners.
- Notificaciones por correo
- Consultar exportaciones