Guía de Configuración de Webhooks

Los webhooks permiten que la plataforma Leypal envíe notificaciones en tiempo real a tu servidor en el momento en que ocurre algo — un firmante completa un documento, una verificación de identidad finaliza, o una firma se cancela. En lugar de hacer polling a la API cada pocos segundos para detectar cambios, tu endpoint recibe una única solicitud HTTP POST en el instante en que ocurre el evento.

Por qué importan los webhooks:

• Tiempo real: Tu sistema reacciona de inmediato — sin bucles de polling, sin datos desactualizados
• Confiable: Leypal reintenta las entregas fallidas automáticamente, por lo que las interrupciones transitorias no causan eventos perdidos
• Selectivo: Suscríbete solo a los tipos de eventos relevantes para tu integración
• Seguro: Cada payload está firmado con HMAC-SHA256 para que puedas verificar la autenticidad antes de procesarlo

Escenarios comunes donde los webhooks son esenciales: actualizar un registro de base de datos cuando se completa una firma, enviar un correo de confirmación a un cliente, o desencadenar un flujo de trabajo cuando la verificación de identidad es aprobada.

Prerrequisitos

Antes de registrar un webhook, asegúrate de tener:

• Una Clave API de Leypal activa con permisos de webhook habilitados (ver Autenticación API)
• Un endpoint HTTPS accesible públicamente — las URLs de localhost no funcionan; Leypal debe poder llegar a tu servidor desde internet
• La capacidad de manejar solicitudes HTTP POST y devolver un código de respuesta en menos de 30 segundos
• Un plan para la verificación de firmas — cubierto en la Guía de Verificación de Webhooks

HTTPS requerido: Leypal solo entrega webhooks a URLs https://. Los endpoints http:// simples serán rechazados durante el registro. Para desarrollo local, usa una herramienta de tunelización como ngrok o Cloudflare Tunnel.

Registro Paso a Paso

Paso 1: Abre la Sección de Webhooks

1. Inicia sesión en el Panel de control de Leypal
2. Navega a Configuración → Claves API
3. Selecciona la Clave API que deseas asociar con el webhook
4. Desplázate hacia abajo hasta la sección Webhooks dentro de la configuración de la Clave API
5. Haz clic en Agregar Endpoint de Webhook

Cada endpoint de webhook está vinculado a una Clave API específica. Esto significa que las entregas de webhook siempre llevarán la identidad de la clave que los registró.

Paso 2: Ingresa Tu URL de Webhook

En el campo URL del Endpoint, ingresa la URL pública de tu servidor que recibirá los eventos de webhook:

https://tudominio.com/webhooks/leypal

Requisitos de URL:

• Debe comenzar con https://
• Debe ser accesible desde el internet público
• La ruta es tu elección — usa cualquier ruta que tenga sentido en tu aplicación

Para pruebas locales: Expón tu servidor local con ngrok:

ngrok http 3000
# Leypal entregará a: https://abc123.ngrok.io/webhooks/leypal

Paso 3: Selecciona los Tipos de Eventos

Elige qué eventos debe recibir tu endpoint. Puedes suscribirte a tipos de eventos individuales o a todos los eventos a la vez.

Eventos de firma:

Eventos de verificación de identidad:

Recomendación: Comienza solo con los eventos que tu integración maneja activamente. Siempre puedes agregar más después. Recibir eventos que ignoras desperdicia los recursos de tu servidor y puede aumentar el ruido en tus logs.

Paso 4: Genera Tu Secreto de Webhook

Después de ingresar la URL y seleccionar los tipos de eventos, haz clic en Generar Secreto. Leypal creará un string secreto único vinculado a este endpoint.

Importante: Copia el secreto inmediatamente. Se muestra solo una vez y no puede recuperarse después de cerrar el diálogo. Si lo pierdes, debes rotarlo (ver Rotación de Secreto más abajo).

Guarda el secreto en las variables de entorno de tu aplicación:

# .env
LEYPAL_WEBHOOK_SECRET="whsec_tu_secreto_aqui"

Este secreto se usa para verificar que las solicitudes de webhook entrantes realmente provienen de Leypal. El proceso de verificación usa HMAC-SHA256 — consulta la Guía de Verificación de Webhooks para los detalles de implementación.

Paso 5: Guarda y Prueba

Haz clic en Guardar Endpoint para registrar el webhook. Leypal enviará inmediatamente un ping de prueba para verificar que tu endpoint es alcanzable:

• Si tu endpoint responde con 2xx, el registro tiene éxito y el webhook está activo
• Si tu endpoint no es alcanzable o devuelve un error, el panel de control mostrará el código de estado HTTP que Leypal recibió para que puedas diagnosticar el problema

Consejo: Si el ping de prueba falla, verifica que tu servidor esté ejecutándose, que la URL sea accesible públicamente y que la ruta devuelva un 200 OK sin requerir encabezados de autenticación. El payload del ping es un pequeño objeto JSON con event: "ping".

Gestión del Secreto

Almacenando el Secreto de Forma Segura

Nunca codifiques tu secreto de webhook en el código fuente y nunca lo confirmes en control de versiones. Usa variables de entorno o un gestor de secretos.

Desarrollo (archivo .env):

# .env — agrega a .gitignore
LEYPAL_WEBHOOK_SECRET="whsec_tu_secreto_aqui"

# .gitignore
.env
.env.local
.env.*

Producción (recomendado): Guarda el secreto en un servicio de secretos administrado:

• AWS Secrets Manager — recupera en tiempo de ejecución usando el AWS SDK
• HashiCorp Vault — para gestión de secretos autohospedada
• Railway / Heroku / Render — usa la UI de variables de entorno de la plataforma, nunca un archivo de configuración confirmado

Rotación de Secreto

Debes rotar tu secreto de webhook periódicamente (ej., trimestralmente) o de inmediato si sospechas que ha sido comprometido.

Procedimiento de rotación:

1. En el Panel de control de Leypal, navega a Configuración → Claves API → [Tu Clave] → Webhooks
2. Encuentra el endpoint que deseas rotar y haz clic en Rotar Secreto
3. Leypal genera un nuevo secreto y ambos secretos permanecen válidos temporalmente — esto te da tiempo para actualizar tu aplicación sin perder eventos
4. Actualiza la variable de entorno de tu aplicación con el nuevo secreto y redespliega
5. Una vez que estés seguro de que el nuevo secreto funciona, regresa al Panel de control y haz clic en Revocar Secreto Antiguo para desactivarlo

Durante la rotación: Leypal firma cada entrega con el secreto antiguo y el nuevo. Tu código de verificación puede aceptar firmas de cualquiera de los dos hasta que revoques el antiguo. Esto previene la pérdida de eventos durante la ventana de transición.

Señales de que debes rotar inmediatamente:

• El secreto fue confirmado accidentalmente en git
• Tu archivo .env fue expuesto en un incidente de seguridad
• Un miembro del equipo con acceso al secreto abandona tu organización

Códigos de Respuesta HTTP

Tu endpoint debe responder a cada entrega de webhook. Leypal usa tu código de respuesta HTTP para determinar si la entrega fue exitosa.

Qué Espera Leypal

Responde lo más rápido posible — idealmente en 1-2 segundos. Si tu lógica de negocio tarda más, encola el evento y procésalo de forma asíncrona. Devuelve el código de estado HTTP de inmediato después de recibirlo.

Comportamiento por Código de Respuesta

Mejor práctica: Devuelve 200 OK de inmediato después de recibir y encolar el evento. No esperes a que tu lógica de negocio complete antes de responder. Si tu lógica de procesamiento lanza una excepción, Leypal reintentará la entrega aunque ya la hayas procesado — construye tu manejador para que sea idempotente (seguro de ejecutar dos veces con el mismo evento).

Idempotencia

Cada entrega de webhook incluye un ID de evento único en el payload (event.id). Guarda los IDs de eventos procesados en tu base de datos y verifica antes de procesar:

// Pseudo-código: verificación de idempotencia
const eventId = payload.event.id;

const alreadyProcessed = await db.events.findOne({ eventId });
if (alreadyProcessed) {
  // Devuelve 200 de inmediato — entrega duplicada
  return res.status(200).end();
}

await db.events.insert({ eventId });
await processEvent(payload);

return res.status(200).end();

Política de Reintentos

Leypal reintenta automáticamente las entregas fallidas para proteger contra interrupciones transitorias en tu servidor.

Detalles clave:

• Máximo 5 intentos por evento de webhook — incluyendo la entrega inicial
• Backoff exponencial con un retraso base de ~5 minutos entre intentos de reintento
• Después de 5 intentos fallidos, la entrega se marca permanentemente como fallida — sin más reintentos
• Los eventos fallidos son visibles en la sección Historial de Webhooks del Panel de control para el endpoint afectado
• Puedes reproducir manualmente un evento fallido desde el Panel de control con fines de depuración

Consejo de monitoreo: Configura alertas en tu servidor para respuestas 5xx repetidas en tu ruta de webhook. Un pico repentino de errores en esa ruta a menudo significa que un despliegue de código rompió tu manejador.

Visualizando el Historial de Webhooks

El Panel de control de Leypal muestra un registro de cada intento de entrega para cada endpoint registrado:

1. Ve a Configuración → Claves API → [Tu Clave] → Webhooks
2. Haz clic en un endpoint para ver su Historial de Entregas
3. Cada fila muestra: tipo de evento, marca de tiempo, código de estado HTTP devuelto y número de intentos
4. Haz clic en una entrega específica para ver el payload completo de la solicitud y la respuesta de tu servidor

Usa la vista de historial para depurar entregas fallidas, verificar que tu endpoint esté recibiendo los eventos correctos y reproducir eventos durante el desarrollo.

Próximos Pasos

Tu webhook está registrado y tu secreto está guardado de forma segura. Esto es lo que debes hacer a continuación:

• Verificar Firmas de Webhook — Implementa la verificación HMAC-SHA256 para que tu servidor pueda confirmar que los eventos realmente provienen de Leypal. Este es un paso de seguridad obligatorio antes de ir a producción.
• Referencia de Eventos de Webhook — Esquemas completos de payload para todos los tipos de eventos, con JSON de ejemplo para cada uno
• Solucionar Problemas de Entrega de Webhooks — Fallos de entrega comunes y cómo diagnosticarlos

Recordatorio de seguridad: No proceses ningún evento de webhook sin verificar primero su firma HMAC-SHA256. Un endpoint que acepta cualquier solicitud POST entrante sin verificación es vulnerable a eventos falsificados. Consulta Verificar Firmas de Webhook para la implementación completa.