Webhooks — GhostGuard

Setup

Add a webhook endpoint from the Webhooks tab in your dashboard. Enter your HTTPS endpoint URL, select the events you want to receive, and save. GhostGuard generates a unique signing secret for each webhook.

🔒 HTTPS required. All webhook endpoints must use HTTPS. HTTP endpoints are rejected at registration time.

Events

Event	Triggered when
bot.detected	A session scores below the block threshold and is banned
session.suspicious	A session scores in the suspicious range (monitored)
mail.spam	An email connection scores as spam
mail.abuse	An email connection scores as abuse
ban.auto	GhostGuard automatically adds an entry to your ban list

Payload structure

All webhook payloads are JSON with a consistent envelope:

{

  "event":      "bot.detected",

  "session_id": "a3f9c2e1...",

  "score":      12,

  "verdict":    "bot",

  "domain":     "shop.example.com",

  "ip":         "198.51.100.4",

  "reasons":    ["webdriver_flag", "typing_anomaly"],

  "timestamp":  "2026-05-14T18:32:11Z"

}

Signature verification

Every webhook request includes an X-GhostGuard-Signature header containing an HMAC-SHA256 signature of the raw request body using your webhook secret. Always verify this before processing the payload.

<?php

$payload = file_get_contents('php://input');

$sig     = $_SERVER['HTTP_X_GHOSTGUARD_SIGNATURE'] ?? '';

$secret  = 'your-webhook-secret';

$expected = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $sig)) {

  http_response_code(401);

  exit('Invalid signature');

}

$event = json_decode($payload, true);

// Process $event safely

Retries & failures

If your endpoint returns a non-2xx response or does not respond within 5 seconds, GhostGuard marks the delivery as failed and will not automatically retry. Failed delivery counts are visible in the Webhooks tab of your dashboard.

Your endpoint should return 200 OK as quickly as possible and process the event asynchronously if needed. A slow endpoint that causes repeated timeouts will be automatically disabled after 10 consecutive failures.