Einen Webhook-Endpunkt anlegen

Am Ende hat Ihre Organisation einen aktiven Endpunkt, der die gewählten Ereignisse an Ihre https-Adresse bekommt, und Sie haben das Signatur-Secret sicher abgelegt.

Schritte#

Im Portal#

1. Öffnen Sie Einstellungen › Organisation › Webhooks.
2. Klicken Sie auf Endpunkt anlegen. Der Dialog Webhook-Endpunkt anlegen öffnet sich.
3. Tragen Sie unter Endpunkt-URL die Adresse Ihres Empfängers ein, zum Beispiel https://example.com/hooks/signage.
4. Wählen Sie unter Abonnierte Ereignisse im Feld Ereignis suchen … die Ereignistypen. Das Feld filtert den Katalog, jede Wahl legt sich als Chip über das Feld; mindestens ein Ereignis ist nötig.
5. Klicken Sie auf Anlegen.
6. Der Kasten Signatur-Secret — nur jetzt sichtbar erscheint. Klicken Sie auf Secret kopieren und legen Sie den Wert dort ab, wo Ihr Empfänger ihn liest. Erst dann Verstanden.

Anlegen wird erst wählbar, wenn eine Adresse steht und mindestens ein Ereignis als Chip in der Auswahl liegt.

Über die API#

$TOKEN ist das Zugriffstoken einer Anmeldung als Inhaber — ein API-Schlüssel kann die Webhook-Rechte nicht tragen (siehe Anmeldung); $SZENERA_API ist die Basis-URL Ihrer Umgebung.

curl -X POST "$SZENERA_API/v1/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://warenwirtschaft.example.com/hooks/signage",
    "events": ["composition.scene.published", "scheduling.playlist.updated", "media-library.asset.ready"]
  }'

Die Antwort (Status 201) enthält den Endpunkt und — nur in dieser Antwort — das Secret:

{
  "endpoint": {
    "id": "whk_01KPR20K40WEBHK00000000001",
    "tenantId": "tnt_01KERPXZM0ADERAPTHEKE00001",
    "url": "https://warenwirtschaft.example.com/hooks/signage",
    "events": ["composition.scene.published", "scheduling.playlist.updated", "media-library.asset.ready"],
    "active": true,
    "consecutiveFailures": 0,
    "lastDeliveryAt": null,
    "lastFailureAt": null,
    "createdById": "usr_01KFB7QPW0TEAM000000000002",
    "createdAt": "2026-04-21T13:00:00.000Z"
  },
  "secret": "whsec_9tR4mZpQ2xVs7KdHc3JnFb6yWa8EgTu1"
}

Das Secret ist danach nicht mehr abrufbar; geht es verloren, erneuern Sie es (siehe Optionen).

Die Liste events prüft der Server, bevor er den Endpunkt anlegt: Erlaubt sind eine genaue Ereignisart, ein Bereich als composition.* oder * für alles. Ein unbekannter Name ist 422 WebhookEndpoint.EventUnknown und wird in der Antwort genannt — ein Tippfehler soll hier auffallen und nicht als Endpunkt enden, der stumm bleibt. Welche Namen es gibt, liefert GET /v1/webhooks/event-types, siehe Den Ereigniskatalog über die API abrufen.

Optionen#

Beim Bearbeiten bleibt das Signatur-Geheimnis unverändert. Ein deaktivierter Endpunkt behält Adresse, Ereignisse und Zustell-Historie. Ergänzte Ereignisse und ein wieder eingeschalteter Endpunkt werden bis zu eine Stunde später wirksam; neu angelegte Endpunkte sofort.

Regeln für Adresse und Ereignisse#

• Nur https, nur öffentlich. Die Adresse beginnt mit https://; abgewiesen werden localhost, ::1, Namen auf .local sowie 127., 10., 192.168., 169.254. und 172.16. bis 172.31. — Status 422, WebhookEndpoint.UrlInvalid, beim Anlegen wie beim Ändern.
• Mindestens ein Ereignis, bekannte Namen. Erlaubt sind ein genauer Ereignistyp, ein Bereich wie composition.* und *. Ein Tippfehler im Typ wird mit 422 WebhookEndpoint.EventUnknown abgewiesen, ebenso ein Typ, der nicht abonnierbar ist.
• Das Paket zählt beim Anlegen und beim Erneuern des Secrets. Ohne Webhooks im Paket antwortet das Anlegen mit Status 403, Billing.FeatureNotEntitled; im Portal sind Endpunkt anlegen und Secret rotieren gesperrt, über die API bleibt POST /v1/webhooks/{id}/rotate-secret möglich. Bestehende Endpunkte laufen weiter.
• Rechte. Anlegen, Ändern, Erneuern und Löschen brauchen die Rolle Inhaber (webhook.create, webhook.update, webhook.delete); die Liste sehen Inhaber und Manager (webhook.list).

Ergebnis prüfen#

• Der Endpunkt steht in der Liste Webhook-Endpunkte mit Status Aktiv.
• Nach dem nächsten passenden Ereignis zeigt das Zustell-Log eine Zeile mit Status Zugestellt und dem Antwortcode Ihres Servers (etwa „HTTP 200“).
• Ihr Empfänger hat eine Anfrage mit den Kopfzeilen X-Signature, X-Event-Type und X-Delivery-Id gesehen.

Wenn etwas nicht klappt#

Weiterführendes#

• Die Signatur einer Zustellung prüfen
• Ereignistypen: Organisation, Konten, Abrechnung
• Den Ereigniskatalog über die API abrufen
• Wenn keine Zustellung ankommt