ShowBits-Automationen
n8n, Zapier, Make und ähnliche Werkzeuge erreichen einen Workspace mit dem Schlüssel einer Verbindung: Sie lesen seine Clips und Folgen, geben Clips in der Freigabe frei oder schicken sie zurück und erfahren über Webhooks von Ereignissen. In jedem Tarif; die REST-API (Enterprise und OnPremise) braucht es dafür nicht.
Basisadresse https://app.showbits.ai/api/automation/v1 · OpenAPI 3.1 · REST-API
Der Schlüssel
Admins und Owner legen in ShowBits unter Integrationen → n8n, Zapier & Make eine Verbindung an und bekommen ihren Schlüssel einmal angezeigt. Jede Anfrage trägt ihn: Authorization: Bearer sbau_…. Er öffnet nur diese Routen, nur in seinem Workspace. Was er tut, tut er im Namen der Person, die die Verbindung verantwortet; verlässt sie den Workspace oder ist sie nicht mehr Admin, antworten Anfragen mit 403 owner, bis jemand die Verbindung übernimmt.
Freigeben
Ein Clip in der Freigabe wartet auf einen Schritt der Freigabe des Workspaces (approval.stage von approval.stages). POST …/approve und …/reject nennen diesen Schritt in stage: Ist der Clip inzwischen weiter (ein wiederholtes Ereignis, ein zweiter Klick), passiert nichts, die Antwort ist 409 stale mit dem jetzigen Stand. by ist, wer geklickt hat, so wie Ihr Werkzeug es weiß; das Audit-Log hält es so fest.
Embargo
Clips und Folgen unter Embargo sieht eine Verbindung nur, wenn sie dafür angelegt wurde. Sonst fehlen sie in Listen, und ein Clip oder eine Folge antwortet mit 409 embargo und embargoUntil, bis das Embargo endet: Dann kommt episode.embargo_ended.
Fehler
Fehler kommen als JSON {"error": "…"} mit einem festen Wort: 401 unauthorized, 403 inactive oder owner, 404 notFound, 409 stale oder embargo, 422 invalid oder target, 429 tooMany oder limit.
Grenzen
300 Anfragen je Minute und Verbindung, fehlgeschlagene eingerechnet; darüber 429 mit Retry-After. Links zu Dateien (Video, Bilder, WebVTT) sind signiert und gelten eine Stunde: Holen Sie sie, wenn Sie sie brauchen.
Versionen
/v1 ändert sich nur durch Hinzufügen: neue Felder, Routen und Ereignisse. Unbekannte Felder in Antworten bitte ignorieren; unbekannte Felder in Anfragen werden abgelehnt.
In n8n
- Credentials → Add credential → Header Auth: Name
Authorization, WertBearer, ein Leerzeichen und der Schlüssel. - Ein HTTP-Request-Node mit diesem Credential:
GET https://app.showbits.ai/api/automation/v1/meantwortet mit der Verbindung und ihrem Workspace. - Ein Webhook-Node (POST) für die Ereignisse: seine Production-URL in ShowBits bei den Webhooks der Verbindung eintragen, oder den Workflow sich mit
POST …/hooksselbst anmelden lassen. Selbst betriebenes n8n braucht eine https-Adresse, die aus dem Internet erreichbar ist. - Die Signatur mit dem Crypto-Node prüfen (HMAC-SHA256 von
t.body, roher Body) und Wiederholungen an deriddes Ereignisses verwerfen (Remove Duplicates).
Zapier und Make: dasselbe mit ihren HTTP-Modulen (Webhooks by Zapier, die HTTP-App von Make): der Header Authorization an jeder Anfrage, eine Webhook-Adresse für die Ereignisse.
Webhooks
Jedes Ereignis kommt als POST mit ShowBits-Event, ShowBits-Delivery und ShowBits-Signature: t=…,v1=… (HMAC-SHA256 von t.body mit dem Geheimnis des Webhooks), wiederholt über gut einen Tag, solange Ihre Adresse nicht mit 2xx antwortet. Ereignisse nennen den Clip oder die Folge nur mit ID (object); den Rest liefern die Routen. via ist automation für das, was eine Verbindung getan hat.
Diese Ereignisse kann eine Verbindung abonnieren:
clip.approvedclip.deletedclip.forwardedclip.rejectedclip.submittedclip.video_readyepisode.analysedepisode.createdepisode.deletedepisode.embargo_changedepisode.embargo_endedepisode.submitted
import { createHmac, timingSafeEqual } from "node:crypto";
// header: the ShowBits-Signature header; body: the raw request body; secret: whsec_…
export function verify(header, body, secret, toleranceSec = 300) {
const parts = header.split(",").map((p) => p.trim().split("="));
const t = Number(parts.find(([k]) => k === "t")?.[1]);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest();
return parts.some(([k, v]) => k === "v1" && v?.length === 64 && timingSafeEqual(Buffer.from(v, "hex"), expected));
}Routen
Connection
get/meThe connection, its workspace and limits
Mit dem Schlüssel der Verbindung
200The connection ·Connection401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
Clips
get/clipsThe workspace's clips, oldest first, by status and episode
Clips of episodes under embargo only for a connection made to see them.
Mit dem Schlüssel der Verbindung
| Parameter | Ort | Typ | Bedeutung |
|---|---|---|---|
status | query | review | approved | scheduled | published | rejected | |
episodeId | query | string | |
cursor | query | string | |
limit | query | integer |
200A page ·object401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
get/clips/{id}One clip with its texts and links to its files (an hour)
Mit dem Schlüssel der Verbindung
| Parameter | Ort | Typ | Bedeutung |
|---|---|---|---|
id * | path | string |
200The clip ·ClipDetail401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure404Unknown ·Failure409Under embargo (embargo, with its end) ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
Approval
post/clips/{id}/approveApproves the step a clip in review waits for
In the name of the person who answers for the connection; the audit log names the connection and by. Only a clip in review at stage moves: a repeated event or a second click gets 409 stale with where the clip is now, and nothing happens.
Mit dem Schlüssel der Verbindung
| Parameter | Ort | Typ | Bedeutung |
|---|---|---|---|
id * | path | string |
Inhalt (JSON)
stage*integer– The step shown to whoever decided (approval.stage): nothing happens when the clip has moved oncommentstringbystring– Who clicked, as your tool knows them; kept in the audit log as reported
200What happened ·Decision401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure404Unknown ·Failure409stale (the clip moved on) or embargo ·Failure422Invalid ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
post/clips/{id}/rejectSends a clip in review back
In the name of the person who answers for the connection; the audit log names the connection and by. Only a clip in review at stage moves: a repeated event or a second click gets 409 stale with where the clip is now, and nothing happens.
Mit dem Schlüssel der Verbindung
| Parameter | Ort | Typ | Bedeutung |
|---|---|---|---|
id * | path | string |
Inhalt (JSON)
stage*integer– The step shown to whoever decided (approval.stage): nothing happens when the clip has moved oncommentstringbystring– Who clicked, as your tool knows them; kept in the audit log as reported
200What happened ·Decision401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure404Unknown ·Failure409stale (the clip moved on) or embargo ·Failure422Invalid ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
Episodes
get/episodes/{id}One episode: its show, embargo, analysis and clips
Mit dem Schlüssel der Verbindung
| Parameter | Ort | Typ | Bedeutung |
|---|---|---|---|
id * | path | string |
200The episode ·Episode401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure404Unknown ·Failure409Under embargo (embargo, with its end) ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
Webhooks
get/hooksThe connection's webhooks
Mit dem Schlüssel der Verbindung
200Its webhooks ·object401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
post/hooksSubscribes an address to events (the secret comes once)
Events come as a POST signed like the REST API's webhooks (ShowBits-Signature: t=…,v1=HMAC-SHA256 of t.body). They name objects by id only; read them here. At most 10 webhooks per workspace, with the API's.
Mit dem Schlüssel der Verbindung
Inhalt (JSON)
url*string– https, reachable from the internetevents*clip.approved | clip.deleted | clip.forwarded | clip.rejected | clip.submitted | clip.video_ready …[]descriptionstring
201Subscribed ·object401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure422Invalid, or an address ShowBits may not reach (target) ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
delete/hooks/{id}Unsubscribes
Mit dem Schlüssel der Verbindung
| Parameter | Ort | Typ | Bedeutung |
|---|---|---|---|
id * | path | string |
204Gone401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure404Unknown ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure