Empfangen Sie Projektbenachrichtigungen

Bereiten Sie den Empfänger vor

Webhooks senden HTTP-Anfragen bei prüfbereiten Videos, fertigen Exporten, Fehlern oder Abbruch. Integrationen sind mit Max-Abonnements verfügbar.

Benötigt wird eine öffentliche HTTPS-URL für POST, nur Port 443. Localhost und private Netze sind nicht direkt erreichbar. CaptionBolt folgt keinen Weiterleitungen. Lokal nutzen Sie einen öffentlichen HTTPS-Tunnel.

Ersetzen Sie https://receiver.example/captionbolt durch Ihre URL.

Fügen Sie einen Endpunkt hinzu

1. Öffnen Sie Einstellungen → Integrationen.
2. Geben Sie HTTPS-Zieladresse und Ereignisse an.
3. Wählen Sie Webhook hinzufügen.
4. Speichern Sie das Signaturgeheimnis, das nur einmal angezeigt wird.

Es prüft Benachrichtigungen und ist vom API-Schlüssel getrennt.

Auch REST ist möglich. Setzen Sie CAPTIONBOLT_API_KEY mit webhooks:manage gemäß API-Anleitung:

curl --fail-with-body https://api.captionbolt.com/v1/webhooks \
  -H "Authorization: Bearer $CAPTIONBOLT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://receiver.example/captionbolt","events":["project.completed","project.failed"]}'

Die Antwort liefert id und secret. Bewahren Sie das Geheimnis sicher in der Empfängerumgebung auf.

Wählen Sie Ereignisse

| Ereignis | Bedeutung | | --- | --- | | project.ready | Verarbeitung fertig; Prüfung oder Export möglich | | project.completed | Export fertig, Ergebnisse verfügbar; standardmäßig gewählt | | project.failed | Verarbeitung oder Export fehlgeschlagen; standardmäßig gewählt | | project.cancelled | Projekt abgebrochen |

Ereignisse umfassen passende Kontovideoprojekte aus Website, REST oder MCP. Neue Endpunkte erhalten nur zukünftige Ereignisse, keine Wiederholung vergangener Änderungen. Eigenständige Transcripts, gelöschte und abgelaufene Projekte sind ausgeschlossen.

project.ready bedeutet weder exportiert noch von einem Menschen geprüft.

{
  "id": "event-uuid",
  "type": "project.completed",
  "createdAt": "2026-09-27T12:00:00.000Z",
  "data": {
    "projectId": "project-uuid",
    "status": "completed",
    "stage": "export",
    "resultUrl": "https://api.captionbolt.com/v1/projects/project-uuid/result"
  }
}

Ereignisse enthalten Metadaten, keine Videos oder Untertiteltexte. data.resultUrl ist ein authentifizierter REST-Endpunkt. Rufen Sie mit projects:read neue Links ab und laden Sie ohne Schlüssel herunter. Siehe Downloads.

Prüfen Sie eingehende Anfragen

CaptionBolt nutzt Standard Webhooks. Prüfen Sie die Signatur am exakten unveränderten Body vor Auswertung oder Verarbeitung. Header: webhook-id, webhook-timestamp, webhook-signature.

Node.js-Empfängerbeispiel

Dieses Beispiel prüft Signaturen und protokolliert ID und Typ zum Zustellungstest. Es verwendet Node.js 24; andere Sprachen sind möglich. Installieren Sie den JavaScript-Verifier im eigenen Empfängerprojekt:

npm install standardwebhooks
read -r -s -p 'CaptionBolt signing secret: ' CAPTIONBOLT_WEBHOOK_SECRET
export CAPTIONBOLT_WEBHOOK_SECRET
printf '\n'

Speichern Sie als receiver.mjs:

import { createServer } from "node:http";
import { Webhook } from "standardwebhooks";

const secret = process.env.CAPTIONBOLT_WEBHOOK_SECRET;
if (!secret) throw new Error("Set CAPTIONBOLT_WEBHOOK_SECRET.");
const verifier = new Webhook(secret);

createServer(async (request, response) => {
  if (request.method !== "POST" || request.url !== "/captionbolt") {
    response.writeHead(404).end();
    return;
  }
  let event;
  try {
    const chunks = [];
    let size = 0;
    for await (const chunk of request) {
      size += chunk.length;
      if (size > 65536) {
        response.writeHead(413).end();
        return;
      }
      chunks.push(chunk);
    }
    const rawBody = Buffer.concat(chunks).toString("utf8");
    event = verifier.verify(rawBody, {
      "webhook-id": request.headers["webhook-id"],
      "webhook-timestamp": request.headers["webhook-timestamp"],
      "webhook-signature": request.headers["webhook-signature"],
    });
  } catch {
    response.writeHead(400).end("Invalid webhook");
    return;
  }
  console.log("Verified event:", event.id, event.type);
  response.writeHead(204).end();
}).listen(3000, "127.0.0.1");

Starten Sie node receiver.mjs und veröffentlichen Sie /captionbolt über HTTPS oder Tunnel. CaptionBolt benötigt die öffentliche HTTPS-URL statt der lokalen Adresse.

Der Verifier prüft Signatur und Zeitstempel; die Uhr muss stimmen. JSON nicht vor Prüfung parsen und neu serialisieren. Geheimnis und gesamten Body nicht protokollieren.

In Produktion ersetzen Sie Logging durch dauerhafte Annahme: nach id deduplizieren, Ereignis oder Aufgabe vor 2xx speichern und asynchron bearbeiten. Bei Speicherfehlern Fehlerantwort senden, damit Wiederholung möglich ist. Das Beispiel prüft nur Empfang, ohne dauerhafte Warteschlange oder Downloads.

Senden Sie einen Test

1. Starten Sie Empfänger und konfigurieren Sie das Geheimnis.
2. Öffnen Sie den Endpunkt unter Einstellungen → Integrationen, wählen Sie Test senden.
3. Prüfen Sie den Zustellungsverlauf.
4. Bestätigen Sie ein verifiziertes webhook.test im Protokoll.

Nur ein Test darf pro Endpunkt laufen. Warten Sie auf Abschluss und danach mindestens 60 Sekunden. Manuelle Wiederholungen haben ebenfalls Wartezeiten; beachten Sie den zurückgegebenen Zeitraum.

Behandeln Sie webhook.test separat; es steht nicht für ein fertiges Video. Testen Sie Ergebnisabruf mit einem zukünftigen echten Ereignis.

Bei Fehlern URL, Geheimnis, Body und Antwort prüfen. Bestätigen Sie innerhalb von 15 Sekunden. Nicht-2xx, Verbindungsfehler oder fehlende Bestätigung führen zu Wiederholungen.

Verwalten Sie Wiederholungen und Geheimnisse

Benachrichtigungen können doppelt und ungeordnet eintreffen. Nach ID deduplizieren und bei Bedarf aktuellen Projektstatus abfragen.

Drei automatische Versuche: zuerst sofort, etwa eine Minute nach dem ersten Fehler, fünf Minuten nach dem zweiten. Danach endet die Automatik. Empfänger reparieren und Erneut zustellen wählen; gleiche ID, weitere drei Versuche. Verlauf: 30 Tage.

Wählen Sie Geheimnis erneuern, speichern Sie das neue Geheimnis und aktualisieren Sie den Empfänger. Das alte bleibt 24 Stunden gültig; Zustellungen enthalten währenddessen beide Signaturen. Weitere Rotation ist bis zum Ende blockiert.

Deaktivieren stoppt offene Zustellungen; laufende Anfragen können enden. Löschen entfernt auch den Verlauf. Gelöschte oder abgelaufene Projekte stoppen offene Benachrichtigungen. Webhooks verlängern die 14 Tage nicht; Ergebnisse vorher abrufen und speichern.