Webhooks
Ein Webhook meldet Ihren eigenen Systemen, was in einem Arbeitsbereich geschieht: Freigaben, neue Folgen, fertige Videos, veröffentlichte Posts und mehr. ShowBits schickt jedes Ereignis signiert an Ihre Adresse. Webhooks gehören zu den Tarifen Enterprise und OnPremise; in jedem Tarif haben Verbindungen für n8n, Zapier und Make eigene Webhooks.
- Wer es einrichtet
- Admins des Arbeitsbereichs
- Tarife
- Enterprise und OnPremise
- Was ShowBits schickt
- Signierte Ereignisse, die Objekte mit ihrer ID nennen, ohne Namen, Titel oder Texte
Webhook anlegen
Webhooks legen Admins des Arbeitsbereichs an. Ihr System braucht eine Adresse, die POST-Anfragen über https annimmt und aus dem Internet erreichbar ist.
- Öffnen Sie Einstellungen → API.
- Klicken Sie unter Webhooks auf Webhook anlegen.
- Geben Sie die Adresse (https) Ihres Systems ein. Sie muss mit
https://beginnen, darf keinen Benutzernamen und kein Passwort enthalten und muss aus dem Internet erreichbar sein. - Geben Sie bei Bedarf eine Beschreibung ein, zum Beispiel den Namen des Systems.
- Haken Sie unter Ereignisse an, was Ihr System braucht. Das Kästchen einer Gruppe, etwa Clips, wählt alle ihre Ereignisse.
- Klicken Sie auf Anlegen.
- Klicken Sie auf Kopieren und hinterlegen Sie das Geheimnis in Ihrem System. ShowBits zeigt es nur dieses eine Mal.
- Klicken Sie auf Fertig.
Ein Arbeitsbereich hat höchstens 10 Webhooks, die der Verbindungen für n8n, Zapier und Make mitgezählt. Nehmen Sie bei n8n die Production-URL des Webhook-Nodes; der Dialog warnt, wenn Sie die Test-URL eingeben.

Ereignisse und ihr Inhalt
Die Ereignisse stehen in den Gruppen Clips, Folgen, Posts, Zitatkarten, Team, Integrationen, Brand Kits und Arbeitsbereich. Zum Beispiel: clip.approved, wenn ein Clip freigegeben ist, clip.forwarded, wenn er an die nächste Freigabestufe geht, clip.video_ready, wenn sein Video fertig ist, episode.analysed, episode.embargo_ended, post.published, post.failed und clip.delivered für eine Lieferung in Ihr MAM oder DAM.
Jedes Ereignis ist ein POST mit JSON: id (die ID des Ereignisses), type, occurredAt, workspace (ID und Slug), object (Typ und ID der Folge, des Clips oder des Posts), via (app, api, automation oder system) und data mit wenigen unbedenklichen Feldern wie Kanal oder Zeit. Namen, Titel und Texte stehen nie darin; Einzelheiten holt Ihr System über die REST-API.
Signatur prüfen
Jedes Ereignis trägt die Kopfzeilen ShowBits-Event (der Typ des Ereignisses), ShowBits-Delivery (die ID der Zustellung) und ShowBits-Signature: t=…,v1=…. Prüfen Sie die Signatur, bevor Ihr System auf ein Ereignis reagiert.
- Lesen Sie den Inhalt der Anfrage als Rohtext, bevor Ihr System das JSON auswertet.
- Entnehmen Sie
ShowBits-Signatureden Wertt, die Zeit in Unix-Sekunden, und jedenv1-Wert. - Berechnen Sie einen HMAC-SHA256 über
t, einen Punkt und den Rohtext, mit dem ganzen Geheimnis samtwhsec_als Schlüssel, und schreiben Sie das Ergebnis als Hex. - Nehmen Sie das Ereignis nur an, wenn das Ergebnis einem der
v1-Werte entspricht; vergleichen Sie in konstanter Zeit. - Verwerfen Sie das Ereignis, wenn
tälter als fünf Minuten ist.
Einen Tag lang nach einem neuen Geheimnis trägt die Kopfzeile ein zweites v1, signiert mit dem bisherigen Geheimnis. Beispielcode steht in der API-Dokumentation.
Testen, pausieren und Zustellungen prüfen
Jeder Webhook zeigt seinen Host, seinen Status (Aktiv, Pausiert oder Pausiert nach Fehlern), die Beschreibung, die Zahl der Ereignisse und wann die Adresse zuletzt ein Ereignis angenommen hat.
- Klicken Sie auf Testen, um ein Test-Ereignis (
webhook.test) zu schicken. Es geht auch an einen pausierten Webhook. - Klicken Sie auf Zustellungen, um die letzten 20 Ereignisse mit ihrem Ergebnis zu sehen: angenommen (mit dem Statuscode), wird wiederholt (mit der Zahl der Versuche und dem Fehler) oder aufgegeben (mit dem Fehler).
- Klicken Sie auf Pausieren, um keine Ereignisse mehr zu schicken, und auf Fortsetzen, um wieder zu beginnen.
Ereignisse, die geschehen, während ein Webhook pausiert ist, werden nicht nachgeliefert.

Neues Geheimnis erzeugen
Erzeugen Sie ein neues Geheimnis, wenn das alte bekannt geworden sein könnte, oder um es von Zeit zu Zeit zu wechseln. Das bisherige Geheimnis signiert einen Tag lang mit, damit Sie Ihr System ohne Lücke umstellen können.
- Klicken Sie beim Webhook auf Neues Geheimnis.
- Bestätigen Sie mit Neues Geheimnis.
- Klicken Sie auf Kopieren und hinterlegen Sie das neue Geheimnis in Ihrem System.
- Klicken Sie auf Fertig.
Webhook löschen
Ein gelöschter Webhook endet endgültig: Dorthin gehen keine Ereignisse mehr, und offene Zustellungen entfallen.
- Klicken Sie beim Webhook auf das Papierkorb-Symbol (Löschen).
- Bestätigen Sie mit Löschen.
Wiederholungen, automatische Pause und doppelte Ereignisse
Ihre Adresse muss innerhalb von 10 Sekunden mit einem Status von 200 bis 299 antworten; Weiterleitungen folgt ShowBits nicht. Sonst versucht ShowBits es nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden und 24 Stunden erneut und gibt das Ereignis dann auf. Nimmt die Adresse drei Tage lang nichts an, pausiert ShowBits den Webhook (Pausiert nach Fehlern) und schreibt den Admins des Arbeitsbereichs eine E-Mail. Beheben Sie das Problem an der Adresse und klicken Sie dann auf Fortsetzen.
Ein Ereignis kann mehr als einmal ankommen: nach einer Wiederholung oder bei zwei Webhooks mit derselben Adresse. Erkennen Sie Wiederholungen an der id: Sie ist für jeden Versuch und jeden Webhook gleich.
Fragen
Darf die Adresse in unserem internen Netz liegen?
Nein. ShowBits schickt nur an https-Adressen, die aus dem Internet erreichbar sind, ohne Benutzername und Passwort.
Warum steht der Titel des Clips nicht im Ereignis?
Ereignisse nennen Objekte nur mit ihrer ID, so verlassen auf diesem Weg keine Namen, Titel oder Texte ShowBits. Mit einem Token holt Ihr System die Einzelheiten über die REST-API.
Wie lange bleiben Zustellungen gespeichert?
30 Tage. Zustellungen zeigt die letzten 20 eines Webhooks.
Kann unser System seine Webhooks selbst verwalten?
Ja, über die REST-API mit einem Token, das die Berechtigungen webhooks:read und webhooks:write hat. Die Person des Tokens muss Admin des Arbeitsbereichs sein.
Wir haben Creator oder Business. Können wir Ereignisse empfangen?
Webhooks unter Einstellungen → API gehören zu Enterprise und OnPremise. In jedem Tarif haben Verbindungen für n8n, Zapier und Make eigene Webhooks mit derselben Signatur: siehe n8n, Zapier und Make.