# Webhooks einrichten und Zustellungen prüfen

Mit einem Webhook meldet Szenera Ereignisse Ihrer Organisation an Ihre eigene Adresse, sobald sie geschehen, signiert und nachvollziehbar. Statt in Abständen nachzufragen, wird Ihr Programm angerufen.

> **Typ:** anleitung
> **Für wen:** Wer ein eigenes System auf Vorgänge in Szenera reagieren lassen will
> **Voraussetzung:** Die Rechte **Webhooks auflisten** und **Webhooks anlegen**, dazu eine über HTTPS erreichbare Adresse. Neu anlegen und Geheimnisse erneuern geht ab dem Paket Premium. Bestehende Endpunkte bleiben gültig.
> **Ort im Portal:** **Einstellungen › Für Entwickler › Webhooks**, Schaltfläche **Endpunkt anlegen**

## Schritte

### Einen Endpunkt anlegen

1. Öffnen Sie **Einstellungen**, klappen Sie am Fuß der Seitenleiste **Für Entwickler** auf und wählen Sie **Webhooks**.
2. Klicken Sie auf **Endpunkt anlegen**. Der Dialog **Webhook-Endpunkt anlegen** erklärt sich selbst: „Adresse angeben und die Ereignisse wählen, die dorthin zugestellt werden.“
3. Tragen Sie unter **Endpunkt-URL** die Adresse Ihres Empfängers ein. Der Platzhalter zeigt die erwartete Form: `https://example.com/hooks/signage`.
4. Wählen Sie unter **Abonnierte Ereignisse** über **Ereignis hinzufügen**, was Sie angeht. Das Suchfeld **Ereignis suchen …** filtert. Die Liste zeigt nur, was Ihre Organisation überhaupt auslöst: „Auswahl aus den Ereignissen, die Ihre Organisation auslösen kann.“
5. Klicken Sie auf **Anlegen**.
6. Kopieren Sie das Geheimnis unter **Signatur-Secret — nur jetzt sichtbar** mit **Secret kopieren** und legen Sie es sicher ab. Schließen Sie mit **Verstanden**.

![Der Dialog Webhook-Endpunkt anlegen mit dem Feld Endpunkt-URL und seinem Platzhalter (1), dem Suchfeld Ereignis hinzufügen unter Abonnierte Ereignisse (2), dem Hinweis auf die Ereignisse, die die eigene Organisation auslösen kann (3), und der Schaltfläche Anlegen (4)](/de/developers/bilder/0862ab28-create-webhook-endpoint-dialog.png)

### Zustellungen auf Echtheit prüfen

Ein Webhook ohne Prüfung nimmt jede Nachricht an, die die Adresse kennt. Deshalb trägt jede Zustellung drei Kopfzeilen. Das Portal führt sie unter **Zustellungen auf Echtheit prüfen** mit auf:

| Kopfzeile | Was sie trägt |
|---|---|
| `X-Signature` | HMAC-SHA256 über den rohen Rumpf, mit Ihrem Signatur-Geheimnis, base64url-kodiert. |
| `X-Event-Type` | Die Ereignisart. Ihr Empfänger kann danach verzweigen, ohne den Rumpf zu lesen. |
| `X-Delivery-Id` | Nummer der Zustellung. Verarbeiten Sie jede Nummer genau einmal. Ein Wiederholungsversuch trägt dieselbe. |

Prüfen Sie die Signatur, bevor Sie den Inhalt verarbeiten. Signiert wird der rohe Rumpf, nicht neu erzeugtes JSON — jede Umwandlung kann Reihenfolge oder Abstände ändern. Der Vergleich läuft in konstanter Zeit:

```ts
import { createHmac, timingSafeEqual } from 'node:crypto';

export function isFromSignage(rawBody: string, header: string, secret: string): boolean {
  const expected = createHmac('sha256', secret).update(rawBody).digest('base64url');
  const a = Buffer.from(expected);
  const b = Buffer.from(header);
  return a.length === b.length && timingSafeEqual(a, b);
}
```

### Zustellungen prüfen und wiederholen

Das Log setzt das Recht **Zustellungen auflisten** voraus, das Wiederholen zusätzlich **Zustellung wiederholen**.

1. Öffnen Sie in der Zeile des Endpunkts das Menü mit den drei Punkten am rechten Rand und wählen Sie **Zustell-Log**.
2. Lesen Sie je Zeile das **Ereignis** und den **Status**: **Ausstehend**, **Zugestellt**, **Fehlgeschlagen** oder **Wiederholung läuft**. Eine Zustellung, die Szenera nach allen Versuchen aufgegeben hat, trägt **dead**. Hat Ihr Empfänger geantwortet, steht der Antwortcode daneben, etwa **HTTP 500** — daran erkennen Sie, ob die Zustellung überhaupt ankam.
3. Zeilen mit dem Status **Fehlgeschlagen** tragen die Schaltfläche **Erneut zustellen**. Sie stößt genau diese eine Zustellung noch einmal an, ohne den nächsten automatischen Versuch abzuwarten. Das Portal meldet **Zustellung erneut angestoßen**. Bei allen anderen Status bleibt die Zelle leer.
4. **Log ausblenden** schließt die Tabelle.

Ein dauerhaft totes Ziel klopft nicht endlos an: Nach mehr als 20 gescheiterten Zustellungen in Folge schaltet Szenera den Endpunkt selbst auf **Inaktiv**.

![Die Liste der Webhook-Endpunkte mit der Spalte Endpunkt und den abonnierten Ereignissen (1), dem Status Aktiv samt Zeitpunkt des letzten Fehlers (2) und dem aufgeklappten Zustell-Log mit Ereignis und Status (3)](/de/developers/bilder/bb2d0575-webhook-delivery-log.png)

_Das Zeilenmenü selbst schließt beim Aufklappen des Logs. Die Einträge nennt der Schritt darüber. **Erneut zustellen** steht im Bild an keiner Zeile: Die Schaltfläche erscheint nur beim Status **Fehlgeschlagen**._

### Das Geheimnis erneuern

Erneuern, Ändern sowie Ab- und Anschalten setzen das Recht **Webhooks bearbeiten** voraus.

1. Öffnen Sie in der Zeile das Menü mit den drei Punkten und klicken Sie auf **Secret rotieren**. Adresse, abonnierte Ereignisse und die bisherigen Zustellungen bleiben erhalten.
2. Kopieren Sie das neue Geheimnis unter **Signatur-Secret — nur jetzt sichtbar** mit **Secret kopieren** und schließen Sie mit **Verstanden**. Auch dieses sehen Sie genau einmal. Geht es verloren, rotieren Sie erneut.
3. Adresse und Ereignisse ändern Sie stattdessen über **Bearbeiten**: „Das Signatur-Geheimnis bleibt dabei unverändert.“

## Ergebnis prüfen

Der Endpunkt steht in der Liste mit **Endpunkt** und **Status**. **Aktiv** heißt: Es wird zugestellt. **Inaktiv** heißt: Es wird nicht zugestellt. Entweder haben Sie den Endpunkt mit **Deaktivieren** angehalten, oder Szenera hat ihn nach mehr als 20 gescheiterten Zustellungen in Folge selbst abgeschaltet — dann steht daneben **letzter Fehler …** mit dem Zeitpunkt. **Aktivieren** nimmt ihn in beiden Fällen wieder in Betrieb. Solange nichts passiert ist, meldet das Log **Noch keine Zustellungen.**

**Löschen** entfernt den Endpunkt nach der Rückfrage **Webhook-Endpunkt löschen?** endgültig. Dafür brauchen Sie das Recht **Webhooks löschen**. Jede dieser Änderungen steht im **Änderungsprotokoll**.

## Wenn etwas nicht klappt

| Symptom | Ursache | Lösung |
|---|---|---|
| **Anlegen fehlgeschlagen** | Der Endpunkt wurde nicht angelegt. | Prüfen, ob die Adresse über HTTPS erreichbar ist, und erneut auf **Anlegen** klicken. |
| **Ändern fehlgeschlagen**, **Rotation fehlgeschlagen** oder **Löschen fehlgeschlagen** | Der bisherige Stand gilt unverändert weiter. | Den Vorgang erneut aufrufen. Statt **Löschen** geht ersatzweise **Deaktivieren**. |
| **Retry fehlgeschlagen** | Die erneute Zustellung ließ sich nicht anstoßen. | **Erneut zustellen** noch einmal klicken und prüfen, ob Ihr Empfänger erreichbar ist. |
| **Zustell-Log konnte nicht geladen werden.** | Die Tabelle ließ sich nicht abrufen. | Log schließen und erneut öffnen. |

## Weiterführendes

- [Benachrichtigungen: Posteingang und Zustellwege](/de/organization/notifications)
- [Was können eigene Programme mit Szenera tun?](/de/developers/about-integrations)
- [Einen API-Schlüssel erzeugen, rotieren und widerrufen](/de/developers/create-api-key)