Webhooks

Receive real-time notifications when audits complete, alerts trigger, or scores change.

Supported Providers

GeoKit Cloud supports 4 webhook providers:

Generic HTTP

Send POST requests to any HTTP endpoint with HMAC signature verification.

Slack

Rich block messages with custom channel, username, and emoji support.

Discord

Color-coded embeds with custom username and avatar.

Telegram

HTML-formatted messages via Bot API with bot token and chat ID.

Webhook Events

audit.completed

Fired when an audit finishes running.

Payload:

{
  "event": "audit.completed",
  "timestamp": "2026-02-09T12:34:56Z",
  "data": {
    "siteId": "abc123",
    "url": "https://example.com",
    "score": 87,
    "grade": "B",
    "duration": 2341
  }
}

alert.triggered

Fired when an alert condition is met (e.g., score drops below threshold).

score.changed

Fired when a site's score changes from the previous audit.

Setup

Create webhooks from the GeoKit Cloud dashboard Settings page.

Required Fields

• URL: The endpoint to receive webhook payloads
• Events: Select which events trigger this webhook
• Provider: Choose generic, Slack, Discord, or Telegram

HMAC Signature Verification

All generic webhooks include an X-GeoKit-Signature header for verification:

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${hmac}`)
  );
}

// Usage
const isValid = verifyWebhook(
  req.body,
  req.headers['x-geokit-signature'],
  process.env.WEBHOOK_SECRET
);

Retry Logic

Webhook delivery uses exponential backoff with 3 retry attempts:

1. Initial attempt: Immediate
2. Retry 1: After 10 seconds
3. Retry 2: After 60 seconds
4. Retry 3: After 5 minutes

Rate Limits

Next Steps

• GeoKit Cloud - Create webhook configurations
• API Reference - Use GeoKit programmatically
• Scoring System - Understand alert triggers