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

  1. Credentials → Add credential → Header Auth: Name Authorization, Wert Bearer, ein Leerzeichen und der Schlüssel.
  2. Ein HTTP-Request-Node mit diesem Credential: GET https://app.showbits.ai/api/automation/v1/me antwortet mit der Verbindung und ihrem Workspace.
  3. 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 …/hooks selbst anmelden lassen. Selbst betriebenes n8n braucht eine https-Adresse, die aus dem Internet erreichbar ist.
  4. Die Signatur mit dem Crypto-Node prüfen (HMAC-SHA256 von t.body, roher Body) und Wiederholungen an der id des 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:

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

  • 200 The connection · Connection
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 429 Too 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

ParameterOrtTypBedeutung
statusqueryreview | approved | scheduled | published | rejected
episodeIdquerystring
cursorquerystring
limitqueryinteger
  • 200 A page · object
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 429 Too 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

ParameterOrtTypBedeutung
id *pathstring
  • 200 The clip · ClipDetail
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 404 Unknown · Failure
  • 409 Under embargo (embargo, with its end) · Failure
  • 429 Too 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

ParameterOrtTypBedeutung
id *pathstring

Inhalt (JSON)

  • stage * integer – The step shown to whoever decided (approval.stage): nothing happens when the clip has moved on
  • comment string
  • by string – Who clicked, as your tool knows them; kept in the audit log as reported
  • 200 What happened · Decision
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 404 Unknown · Failure
  • 409 stale (the clip moved on) or embargo · Failure
  • 422 Invalid · Failure
  • 429 Too 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

ParameterOrtTypBedeutung
id *pathstring

Inhalt (JSON)

  • stage * integer – The step shown to whoever decided (approval.stage): nothing happens when the clip has moved on
  • comment string
  • by string – Who clicked, as your tool knows them; kept in the audit log as reported
  • 200 What happened · Decision
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 404 Unknown · Failure
  • 409 stale (the clip moved on) or embargo · Failure
  • 422 Invalid · Failure
  • 429 Too 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

ParameterOrtTypBedeutung
id *pathstring
  • 200 The episode · Episode
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 404 Unknown · Failure
  • 409 Under embargo (embargo, with its end) · Failure
  • 429 Too many requests a minute (tooMany), or a limit reached (limit) · Failure

Webhooks

get/hooksThe connection's webhooks

Mit dem Schlüssel der Verbindung

  • 200 Its webhooks · object
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 429 Too 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 internet
  • events * clip.approved | clip.deleted | clip.forwarded | clip.rejected | clip.submitted | clip.video_ready …[]
  • description string
  • 201 Subscribed · object
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 422 Invalid, or an address ShowBits may not reach (target) · Failure
  • 429 Too many requests a minute (tooMany), or a limit reached (limit) · Failure
delete/hooks/{id}Unsubscribes

Mit dem Schlüssel der Verbindung

ParameterOrtTypBedeutung
id *pathstring
  • 204 Gone
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 404 Unknown · Failure
  • 429 Too many requests a minute (tooMany), or a limit reached (limit) · Failure

Zurück zu showbits.de