Webhook Format

SilentShield can send real-time notifications to your server via webhooks. Configure webhook URLs in Dashboard → Notifications.

Payload Structure

All webhook payloads follow this structure:

{"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"}}

Event Types

Event	Description
`bot_detected`	Triggered when a request is classified as a bot.
`bot_spike`	Triggered when bot detections exceed your alert threshold within the configured window.
`quota_warning`	Triggered when quota usage reaches 80% or 90%.
`quota_exceeded`	Triggered when your monthly quota is exceeded.
`domain_verification_failed`	Triggered when a domain re-verification check fails.
`key_rotated`	Triggered when an API key is rotated.

Signature Verification

Every webhook includes an X-SilentShield-Signature header containing an HMAC-SHA256 signature. Verify this signature to ensure the webhook is authentic.

Get the raw request body (as a string, before parsing)
Get the X-SilentShield-Signature header value
Compute HMAC-SHA256 of the body using your webhook secret as the key
Compare the computed signature with the header value

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)
  );
}

Retry Policy

If your endpoint returns a non-2xx status code or times out (10 seconds), SilentShield retries the delivery up to 3 times with exponential backoff (1 minute, 5 minutes, 30 minutes). After 3 failed attempts, the webhook is marked as failed and visible in Dashboard → Notifications → Failed Deliveries.

Webhook Secret

Your webhook secret is generated when you create a webhook endpoint in the dashboard. You can view or regenerate it under Dashboard → Notifications → Webhooks → Edit.