Webhooks — GEOCitation API Docs

Webhooks

GEOCitation sends a POST request to your configured webhook URL when an audit completes or fails.

Configuring a Webhook

Set a webhook URL when creating your API key in your dashboard. It applies to every audit launched with that key. You'll receive a webhook secret — use it to verify incoming requests.

Secret Shown Once

The webhook secret is shown only at key creation time. Save it immediately to your environment variables.

Webhook Events

Two events are sent:

audit.completed

The audit finished successfully. The payload includes quality and timing data.

audit.failed

The audit failed. Check the error_message field for details.

json

// audit.completed payload
// Headers: X-GEOCitation-Event: audit.completed
//          X-GEOCitation-Signature: sha256=...
{
  "event": "audit.completed",
  "audit_id": "3227a3e3-1a2b-4c5d-8e9f-000000000000",
  "status": "completed",
  "quality_status": "success",
  "total_ms": 305000
}

// audit.failed payload
// Headers: X-GEOCitation-Event: audit.failed
//          X-GEOCitation-Signature: sha256=...
{
  "event": "audit.failed",
  "audit_id": "3227a3e3-1a2b-4c5d-8e9f-000000000000",
  "status": "failed",
  "error_message": "pipeline_timeout"
}

Verifying the Signature

Every webhook includes an X-GEOCitation-Signature header (HMAC-SHA256) and an X-GEOCitation-Event header identifying the event type. Verify the signature to ensure the request came from GEOCitation.

python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    """Verify X-GEOCitation-Signature header."""
    expected = "sha256=" + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

typescript

import { createHmac, timingSafeEqual } from "crypto"

function verifyWebhook(
  rawBody: Buffer,
  signature: string,
  secret: string
): boolean {
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex")
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

Retry Policy

GEOCitation retries failed webhook deliveries at 0s, 30s, and 5 minutes. Your endpoint must return a 2xx status to acknowledge receipt.

Data Models

Errors