Webhooks

Webhooks allow VisitorFilters to send real-time notifications to your server when specific events occur. This enables integration with your existing infrastructure, incident management, or custom automation.

Setting Up Webhooks

Go to Sites → [Your Site] → Webhooks
Click Add Endpoint
Enter your endpoint URL (must be HTTPS)
Select the events you want to receive
Save — you'll receive a signing secret

Available Events

Event	Trigger
`visitor.blocked`	A visitor was blocked by a rule
`visitor.challenged`	A visitor was shown a challenge
`ban.created`	A new ban was added (manual or automatic)
`ban.expired`	A ban expired or was lifted
`anomaly.detected`	Risk score exceeded threshold
`rate_limit.exceeded`	A visitor exceeded rate limits

Payload Format

All webhook payloads follow a consistent structure:

{
  "id": "evt_abc123",
  "type": "visitor.blocked",
  "timestamp": "2025-05-22T14:30:00Z",
  "site_id": "site_xyz",
  "data": {
    "visitor_ip": "203.0.113.42",
    "country": "CN",
    "rule_id": "rule_456",
    "action": "block",
    "reason": "Geo block: CN"
  }
}

Signature Verification

Every webhook request includes an X-VF-Signature header containing an HMAC-SHA256 signature. Verify it to ensure the payload came from VisitorFilters:

$payload = file_get_contents('php://input');
$signature = hash_hmac('sha256', $payload, $webhookSecret);

if (! hash_equals($signature, $_SERVER['HTTP_X_VF_SIGNATURE'])) {
    http_response_code(401);
    exit;
}

Retry Policy

If your endpoint returns a non-2xx status code, we retry delivery:

1st retry: 30 seconds
2nd retry: 5 minutes
3rd retry: 30 minutes
4th retry: 2 hours
5th retry: 24 hours

After 5 failed attempts, the delivery is marked as failed. You can manually retry from the dashboard.

Best Practices

Respond with 200 OK quickly — process the payload asynchronously if needed.
Always verify the signature before processing.
Use idempotency — webhooks may be delivered more than once.
Monitor your endpoint's health in Webhooks → Deliveries.