Endpoints de Webhook
Cada organización puede configurar múltiples endpoints para recibir notificaciones de eventos.
Campos del Endpoint
| Campo | Descripción |
|---|---|
| URL | Dirección HTTPS que recibirá las notificaciones |
| Descripción | Descripción del endpoint (máx 255 caracteres) |
| Eventos | Lista de tipos de eventos suscritos |
| Secreto | Clave HMAC-SHA256 para validación de firma |
| Activo | Si el endpoint está habilitado |
Creando un Endpoint
Al crear, el sistema genera automáticamente un secreto (whsec_...) que se muestra solo en la creación. Almacénelo de forma segura — es necesario para validar las firmas de los webhooks.
Firma de los Webhooks
Cada entrega incluye un header de firma:
X-Webhook-Signature: t=<timestamp>,v1=<sha256_hex>
Verificación
- Extraiga el timestamp y la firma del header
- Reconstruya:
${timestamp}.${payload_json} - Calcule HMAC-SHA256 usando el secreto
- Compare con la firma (comparación timing-safe)
Rotación de Secreto
Cuando sospeche que el secreto fue comprometido, use la rotación de secreto. Un nuevo secreto se genera y el anterior se invalida inmediatamente.
Prueba de Webhook
Envíe un payload de prueba para verificar si el endpoint está configurado correctamente. El resultado incluye el código HTTP y la respuesta recibida.
Desactivación Automática
Después de 10 fallos consecutivos de entrega, el endpoint se desactiva automáticamente. Para reactivar, corrija el problema y actualice el endpoint a activo.
Protección contra SSRF
Las URLs se validan para rechazar IPs privadas y localhost, previniendo ataques de Server-Side Request Forgery.