# Webhooks einrichten und Zustellungen prüfen

Am Ende steht ein Endpunkt, an den Szenera die Ereignisse Ihrer Organisation meldet — unterschrieben, nachvollziehbar und einzeln wiederholbar. Statt im Takt zu fragen, lassen Sie sich rufen. Nicht zu verwechseln mit **Benachrichtigungen**: dort legen Sie fest, wie Szenera Sie erreicht, hier, wie Ihre Organisation ein fremdes System erreicht.

> **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 › Organisation › Webhooks**, Schaltfläche **Endpunkt anlegen**

## Schritte

### Einen Endpunkt anlegen

1. Öffnen Sie **Einstellungen**, wechseln Sie ins Register **Organisation** und dort in **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/docs/developers/bilder/207521a9-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/docs/developers/bilder/e213b308-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 | Bedeutung | 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/docs/organization/notifications)
- [Was können eigene Programme mit Szenera tun?](/de/docs/developers/about-integrations)
- [Einen API-Schlüssel erzeugen, rotieren und widerrufen](/de/docs/developers/create-api-key)