Webhooks — GEOCitation API Docs

Webhooks

GEOCitation envoie une requête POST à votre URL webhook configurée lorsqu'un audit se termine ou échoue.

Configurer un Webhook

Définissez une URL webhook lors de la création de votre clé API dans votre dashboard. Elle s'applique à tous les audits lancés avec cette clé. Vous recevrez un secret webhook — utilisez-le pour vérifier les requêtes entrantes.

Secret Affiché Une Seule Fois

Le secret webhook n'est affiché qu'au moment de la création de la clé. Enregistrez-le immédiatement dans vos variables d'environnement.

Événements Webhook

Deux événements sont envoyés :

audit.completed

L'audit s'est terminé avec succès. Le payload inclut des données de qualité et de timing.

audit.failed

L'audit a échoué. Vérifiez le champ error_message pour les détails.

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

Vérifier la Signature

Chaque webhook inclut un en-tête X-GEOCitation-Signature (HMAC-SHA256) et un en-tête X-GEOCitation-Event identifiant le type d'événement. Vérifiez la signature pour vous assurer que la requête provient bien de 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))
}

Politique de Réessai

GEOCitation réessaie les livraisons de webhook échouées à 0s, 30s et 5 minutes. Votre endpoint doit retourner un statut 2xx pour accuser réception.

Modèles de Données

Erreurs