# Webhooks einrichten und Signaturen prüfen

Wie Ihr System erfährt, wenn eine Prüfung fertig oder eine Erklärung veraltet ist – mit Ereignissen, Nutzlast, Signaturprüfung und Wiederholungen.

**Kurz gesagt**

- Ein Webhook ruft Ihre HTTPS-Adresse auf, sobald ein gewähltes Ereignis eintritt – für alle Websites der Organisation.
- Jeder Aufruf ist mit HMAC-SHA256 signiert; prüfen Sie Signatur und Zeitstempel, bevor Sie etwas tun.
- Antworten Sie mit einem Statuscode 2xx. Fehlgeschlagene Zustellungen werden wiederholt; nach anhaltenden Fehlern wird der Endpunkt abgeschaltet.

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

1. „Organisation“ → Webhooks öffnen.
2. Unter „Webhook anlegen“ die Adresse eintragen – sie muss mit `https://` beginnen – und optional eine Beschreibung.
3. Unter „Ereignisse“ auswählen, was Sie erhalten wollen. Nichts auszuwählen heißt: alle.
4. 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](https://barrierepruefung.de/hilfe/fassungen#veraltet). |

## Aufbau eines Aufrufs

Jeder Aufruf ist ein `POST` mit einem JSON-Rumpf:

```json
{
  "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:

1. `t` und `v1` aus dem Header lesen.
2. Den **unveränderten** Rumpf nehmen – nicht erst als JSON einlesen und neu schreiben.
3. HMAC-SHA256 über `t`, einen Punkt und den Rumpf berechnen und in konstanter Zeit mit `v1` vergleichen.
4. 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:

```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](https://barrierepruefung.de/hilfe/wordpress-einrichten#token).

---

Zuletzt gegen das Produkt geprüft: 2026-09-13 · https://barrierepruefung.de/hilfe/webhooks