Webhooks

Bei Abschluss einer Analyse sendet Adlass Extract einen POST an Ihre Webhook-URL: analysis.succeeded oder analysis.failed. Der Body enthält das gleiche Objekt wie GET /v1/analyses/:id:

{
  "id": "<delivery_id>",
  "event": "analysis.succeeded",
  "created_at": "2026-07-28T12:00:00.000Z",
  "data": { "id": "<analysis_id>", "status": "succeeded", … }
}

Die URL kommt pro Request (webhook_url) oder als Account-Endpoint aus dem Dashboard; der Request-Wert überschreibt den Account-Default. Nur öffentliche HTTPS-Endpunkte sind zulässig.

Jede Zustellung trägt den Header extract-signature: t=<timestamp>,v1=<signatur>. Die Signatur ist ein HMAC-SHA256 über `${timestamp}.${body}` mit Ihrem Signing-Secret (Dashboard → Webhooks):

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyExtractSignature(header, rawBody, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((part) => part.split("=", 2)),
  );
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 ?? "", "hex");
  if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
  const ageSeconds = Math.abs(Date.now() / 1000 - Number(parts.t));
  return ageSeconds < 300;
}

Prüfen Sie den Timestamp gegen Replay-Angriffe (Toleranz z. B. 5 Minuten) und antworten Sie mit einem 2xx-Status, sobald Sie das Event angenommen haben — die Verarbeitung sollte asynchron erfolgen.

Antwortet Ihr Endpoint nicht mit 2xx, wird die Zustellung mit exponentiellem Backoff (mit Jitter) über rund 24 Stunden wiederholt, maximal 8 Versuche. Danach gilt sie als aufgegeben. Jede Zustellung ist im Dashboard-Zustell-Log mit Versuchen, Statuscode und Fehler sichtbar.

Aufgegebene oder fehlgeschlagene Zustellungen lassen sich im Dashboard per Replay erneut anstoßen. Unabhängig davon bleibt das Ergebnis 7 Tage per GET /v1/analyses/:id abrufbar — Polling ist der verlässliche Fallback bei Webhook-Ausfällen.