Wie richte ich einen Webhook ein?

Ab Tarif Elite

Kurzantwort

Öffne Verwaltung → Webhooks, klicke „Webhook erstellen” und gib Name, Ziel-URL und die abonnierten Ereignisse (kommagetrennt, z. B. asset.created) an. Nach dem Speichern zeigt Notory das Signatur-Secret genau einmal. Sichere es sofort. Mit „Test senden” schickst du ein signiertes ping-Ereignis und siehst direkt, ob dein Endpunkt antwortet.

Voraussetzungen

Dein Empfänger muss einen HTTP-POST mit JSON entgegennehmen, innerhalb von 10 Sekunden mit einem 2xx-Status antworten und sollte die Signatur prüfen.

Webhooks öffnen. Verwaltung → Webhooks („Signierte HTTP-Callbacks an externe Systeme bei Ereignissen senden. Das Secret wird nur einmal angezeigt.”).

Screenshot ausstehend admin-webhooks-01 Webhook-Verwaltung mit Liste der Webhooks und Schaltfläche 'Webhook erstellen'

Die Webhook-Verwaltung des Mandanten (ab Tarif Elite).
Webhook erstellen. Klicke „Webhook erstellen” und fülle aus:
- Name: z. B. „Ticket-System”.
- URL: der HTTPS-Endpunkt deines Systems.
- Ereignisse (kommagetrennt): z. B. asset.created (die verfügbaren Ereignisse: Welche Events gibt es?).
Secret sichern. Nach dem Speichern erscheint: „Signatur-Secret, jetzt kopieren, es wird nicht erneut angezeigt:”. Hinterlege es im Secret-Store deines Empfängers: Du brauchst es für die Signaturprüfung.

Screenshot ausstehend admin-webhooks-02 Einmalige Anzeige des Signatur-Secrets nach dem Erstellen eines Webhooks

Das Signatur-Secret erscheint genau einmal, direkt nach dem Erstellen.
Testen. Klicke „Test senden”: Notory schickt ein signiertes ping-Ereignis an deine URL und zeigt das Ergebnis (Status-Code bzw. Fehler) direkt an.

Screenshot ausstehend admin-webhooks-03 Testzustellung eines Webhooks mit Ergebnisanzeige (Status-Code) und Zustellprotokoll

'Test senden' verschickt ein signiertes ping-Ereignis und protokolliert das Ergebnis.

Per REST-API: POST /api/v1/webhooks mit Name, URL und Ereignisliste. Das Secret erzeugt der Server. Es steht nur in dieser einen Antwort:

curl -X POST https://demo.notory.io/api/v1/webhooks \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ticket-System",
    "url": "https://tickets.acme.example/hooks/notory",
    "events": ["asset.created"]
  }'

{
  "id": "018f9f44-5e6f-7a77-b182-9c0d1e2f3a41",
  "tenant_id": "3d9b0c12-4e5a-4f88-b1c7-2a9e6d4f0011",
  "name": "Ticket-System",
  "url": "https://tickets.acme.example/hooks/notory",
  "events": ["asset.created"],
  "active": true,
  "created_at": "2026-07-08T11:02:13Z",
  "updated_at": "2026-07-08T11:02:13Z",
  "secret": "wJalrXUtnFEMI…-nur-jetzt-sichtbar"
}

Testen und verwalten:

curl -X POST https://demo.notory.io/api/v1/webhooks/018f9f44-5e6f-7a77-b182-9c0d1e2f3a41/test \
  -H "Authorization: Bearer inv_dein_token"

curl -H "Authorization: Bearer inv_dein_token" https://demo.notory.io/api/v1/webhooks
curl -X DELETE -H "Authorization: Bearer inv_dein_token" \
  https://demo.notory.io/api/v1/webhooks/018f9f44-5e6f-7a77-b182-9c0d1e2f3a41

Mögliche Fehler: 403 (kein Administrator oder Feature webhooks nicht lizenziert, „The Webhooks module is not included in the ’…’ plan”), 404 (Webhook gehört einem anderen Mandanten), 422 (leerer Name/URL).

Was passiert dabei?

Secret serverseitig erzeugt. Das Signatur-Secret (32 zufällige URL-sichere Bytes) erstellt Notory selbst. Du kannst keines vorgeben. Es wird für die HMAC-SHA256-Signatur jeder Zustellung verwendet und nach der Erstellungs-Antwort nie wieder ausgegeben. Secret verloren? Webhook löschen und neu anlegen (Rotation).
Mandantengebunden und sofort aktiv. Der Webhook gehört deinem Mandanten und wird mit active: true angelegt. Er empfängt nur Ereignisse seines Mandanten, und zwar nur die, die in seiner Ereignisliste stehen.
Kein Bearbeiten-Endpunkt. URL oder Ereignisliste ändern = Webhook löschen und neu anlegen (dabei entsteht ein neues Secret; Empfänger anpassen!).
Zustellung im Hintergrund. Ereignisse werden nach der eigentlichen Aktion best-effort zugestellt (die auslösende API-Antwort wartet nicht auf deinen Server). Jede Zustellung wird mit Status-Code bzw. Fehler im Zustellprotokoll festgehalten.
ping zum Verifizieren. Die Testzustellung ist ein reguläres, signiertes Ereignis (X-Webhook-Event: ping) mit {"message": "test delivery"}, ideal, um die Signaturprüfung zu entwickeln.