Formato de Webhook

SilentShield puede enviar notificaciones en tiempo real a su servidor mediante webhooks. Configure las URLs de webhook en Panel → Notificaciones.

Estructura del Payload

Todos los payloads de webhook siguen esta estructura:

{"event": "bot_detected", "timestamp": "2025-01-15T10:30:00Z", "data": {"keyId": "key_abc", "domain": "example.com", "ip": "203.0.113.42", "verdict": "bot", "score": 0.15, "userAgent": "Mozilla/5.0...", "page": "/contact"}}

Tipos de Evento

Event	Description
`bot_detected`	Se activa cuando una solicitud se clasifica como bot.
`bot_spike`	Se activa cuando las detecciones de bots superan su umbral de alerta dentro de la ventana configurada.
`quota_warning`	Se activa cuando el uso de cuota alcanza el 80% o el 90%.
`quota_exceeded`	Se activa cuando se excede su cuota mensual.
`domain_verification_failed`	Se activa cuando falla una verificación de dominio.
`key_rotated`	Se activa cuando se rota una API key.

Verificación de Firma

Cada webhook incluye un encabezado X-SilentShield-Signature que contiene una firma HMAC-SHA256. Verifique esta firma para asegurar que el webhook es auténtico.

Obtenga el cuerpo de la solicitud sin procesar (como cadena, antes del análisis)
Obtenga el valor del encabezado X-SilentShield-Signature
Calcule el HMAC-SHA256 del cuerpo usando su secreto de webhook como clave
Compare la firma calculada con el valor del encabezado

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature)
  );
}

Política de Reintentos

Si su endpoint devuelve un código de estado no-2xx o se agota el tiempo (10 segundos), SilentShield reintenta la entrega hasta 3 veces con retroceso exponencial (1 minuto, 5 minutos, 30 minutos). Después de 3 intentos fallidos, el webhook se marca como fallido y es visible en Panel → Notificaciones → Entregas Fallidas.

Secreto del Webhook

Su secreto de webhook se genera al crear un endpoint de webhook en el panel. Puede verlo o regenerarlo en Panel → Notificaciones → Webhooks → Editar.