Webhooks einrichten und Signaturen prüfen

Ein Webhook erspart Ihrem System das regelmäßige Nachfragen. Er gehört zur Organisation, nicht zu einer einzelnen Website: Ein Endpunkt feuert für alle Websites. Einrichten dürfen ihn „Inhaberin oder Inhaber“ und „Administration“.

Einrichten

„Organisation“ → Webhooks öffnen.
Unter „Webhook anlegen“ die Adresse eintragen – sie muss mit https:// beginnen – und optional eine Beschreibung.
Unter „Ereignisse“ auswählen, was Sie erhalten wollen. Nichts auszuwählen heißt: alle.
Mit „Testereignis“ prüfen, ob Ihr Endpunkt erreichbar ist und die Signatur richtig prüft.

Das Signaturgeheimnis zeigt die Seite über „Signaturgeheimnis anzeigen“. Mit „Neues Geheimnis erzeugen“ tauschen Sie es aus – danach gilt nur noch das neue.

Ereignisse

Ereignis	Wann
`scan.completed`	Eine Prüfung ist abgeschlossen.
`scan.failed`	Eine Prüfung ist fehlgeschlagen.
`declaration.published`	Eine neue Fassung einer Erklärung ist veröffentlicht.
`declaration.outdated`	Eine veröffentlichte Erklärung wurde als veraltet markiert: Fassungen, „veraltet“ und PDF.

Aufbau eines Aufrufs

Jeder Aufruf ist ein POST mit einem JSON-Rumpf:

{
  "id": "01J…",
  "type": "scan.completed",
  "created_at": "2026-09-13T08:14:00+00:00",
  "data": { }
}

data enthält die Angaben zum Ereignis. id ist für alle Endpunkte derselben Zustellung gleich. Verarbeiten Sie jede id nur einmal – eine Wiederholung kann dieselbe Nachricht ein zweites Mal bringen.

Signatur prüfen

Der Header A11y-Signature hat die Form:

A11y-Signature: t=1789286400,v1=5257a869e7…

t ist der Zeitstempel in Sekunden,
v1 ist HMAC-SHA256 über <t>.<Rumpf> mit dem Signaturgeheimnis des Endpunkts, hexadezimal.

So prüfen Sie:

t und v1 aus dem Header lesen.
Den unveränderten Rumpf nehmen – nicht erst als JSON einlesen und neu schreiben.
HMAC-SHA256 über t, einen Punkt und den Rumpf berechnen und in konstanter Zeit mit v1 vergleichen.
Aufrufe verwerfen, deren Zeitstempel älter als 5 Minuten ist. Der Zeitstempel ist Teil der Signatur – ein mitgeschnittener Aufruf lässt sich deshalb nicht später erneut einspielen.

Beispiel in PHP:

[$t, $v1] = [null, null];
foreach (explode(',', $_SERVER['HTTP_A11Y_SIGNATURE'] ?? '') as $teil) {
    [$schluessel, $wert] = array_pad(explode('=', trim($teil), 2), 2, null);
    if ($schluessel === 't') { $t = (int) $wert; }
    if ($schluessel === 'v1') { $v1 = $wert; }
}

$rumpf = file_get_contents('php://input');
$erwartet = hash_hmac('sha256', $t.'.'.$rumpf, $geheimnis);

$gueltig = $t !== null && $v1 !== null
    && hash_equals($erwartet, $v1)
    && abs(time() - $t) <= 300;

Zustellung, Wiederholung, Abschaltung

Erfolgreich ist eine Zustellung, wenn Ihr Endpunkt innerhalb von 15 Sekunden mit einem Statuscode 2xx antwortet. Antworten Sie schnell und verarbeiten Sie danach.
Wiederholt wird bei Zeitüberschreitung, bei Serverfehlern und bei den Statuscodes 408 und 429 – mehrmals, mit wachsendem Abstand bis zu zwei Stunden.
Nicht wiederholt wird bei anderen Statuscodes 4xx: Dort liegt der Fehler in der Anfrage oder der Konfiguration, und eine Wiederholung änderte nichts.
Abgeschaltet wird ein Endpunkt nach wiederholten Fehlversuchen in Folge, und ebenso, wenn seine Adresse auf ein internes Netz zeigt. Die Seite nennt den letzten Fehler; nach der Korrektur schalten Sie ihn wieder ein.

Unter „Letzte Zustellungen anzeigen“ sehen Sie je Zustellung Zeitpunkt, Ereignis und Ergebnis. Mit „Pausieren“ setzen Sie einen Endpunkt vorübergehend aus.

Tokens der Organisation

Auf derselben Seite steht eine Übersicht aller API-Tokens Ihrer Organisation. Erzeugt wird ein Token bei der jeweiligen Website: WordPress-Plugin einrichten und verbinden.