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.

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.

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:

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:

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.

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#

Weiterführendes#

• Benachrichtigungen: Posteingang und Zustellwege
• Was können eigene Programme mit Szenera tun?
• Einen API-Schlüssel erzeugen, rotieren und widerrufen