Webhooks

Event-Modell, Signatur-Verifikation und Retry-Policy für asynchrone Anirag-Events.

Webhooks liefern Events bei länger laufenden Operationen — vor allem Document-Indexing-Jobs, die Sekunden bis Stunden dauern können.

Event-Typen

Event	Beschreibung
`document.indexed`	Dokument wurde erfolgreich gechunked, embedded und ist queryfähig.
`document.failed`	Indexing fehlgeschlagen (z. B. PDF korrupt, Datei zu groß). Inkl. `error_code` + `error_message`.
`collection.reembedding.completed`	Re-Embedding nach Modell-Wechsel ist durchgelaufen.
`trace.created`	Neuer Query-Trace verfügbar. Optional, primär für Compliance-Logging.
`rate_limit.warning`	Workspace nähert sich Plan-Limit (über 80 % verbraucht).

Webhook-Endpoint registrieren

const webhook = await client.webhooks.create({
  url: "https://api.example.com/anirag/webhook",
  events: ["document.indexed", "document.failed"],
  workspace_id: "ws_abc123", // optional, default alle Workspaces der Org
});
 
console.log(webhook.signing_secret);
// → whsec_xxxxx — sichern, wird zur Signatur-Verifikation benötigt

Payload-Format

Alle Events haben dieselbe Hülle:

{
  "id": "evt_8f3a2b1c",
  "type": "document.indexed",
  "created": "2026-05-06T14:32:11.123Z",
  "workspace_id": "ws_abc123",
  "data": {
    "document_id": "doc_xxx",
    "collection_id": "col_yyy",
    "chunk_count": 142,
    "embedding_tokens": 18240,
    "duration_ms": 8740
  }
}

Signatur-Verifikation

Jeder Webhook-Request enthält einen Anirag-Signature-Header. Format:

Anirag-Signature: t=1715000000,v1=abc123...

Pseudocode für die Verifikation:

import { createHmac, timingSafeEqual } from "node:crypto";
 
function verify(rawBody: string, signature: string, secret: string): boolean {
  const [tPart, v1Part] = signature.split(",");
  const timestamp = tPart?.split("=")[1];
  const signature_v1 = v1Part?.split("=")[1];
  if (!timestamp || !signature_v1) return false;
 
  // Replay-Protection: max 5 Minuten alt
  if (Date.now() / 1000 - Number(timestamp) > 300) return false;
 
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
 
  return timingSafeEqual(Buffer.from(signature_v1), Buffer.from(expected));
}

Retry-Policy

Wenn Ihr Endpoint einen Non-2xx-Response liefert oder timeoutet, retried Anirag automatisch:

Retry 1: nach 1 Min
Retry 2: nach 5 Min
Retry 3: nach 30 Min
Retry 4: nach 2 h
Retry 5: nach 12 h

Nach Retry 5 wird das Event als failed markiert. Im Webhook-Log (Web-UI) können Sie es manuell re-senden.

Best Practices

Antworten Sie 200 schnell und queuen Sie die Verarbeitung asynchron. Anirag wartet 10 Sekunden, bevor wir Timeout annehmen.
Idempotenz auf event.id: Anirag kann ein Event mehrfach senden (besonders bei Retry-Storms). Nutzen Sie event.id als Idempotency-Key in Ihrer DB.
HTTPS-only: Webhooks gehen nur an HTTPS-Endpoints. HTTP wird im UI bereits abgelehnt.