Projektbenachrichtigungen empfangen

Ziel erstellen

Fügen Sie nach Freigabe unter Einstellungen → Integrationen einen öffentlichen HTTPS-Empfänger hinzu, wählen Sie Ereignisse und sichern Sie das einmal angezeigte Signaturgeheimnis. Alternativ nutzen Sie einen Schlüssel mit webhooks:manage:

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"]}'

Ersetzen Sie die URL durch Ihren Empfänger. Erlaubt ist nur öffentliches HTTPS auf Port 443 ohne Weiterleitungen. Localhost und private Netze empfangen nicht direkt.

Ereignisse auswählen

project.completed: Export fertig; standardmäßig abonniert.
project.failed: Verarbeitung oder Export fehlgeschlagen; standardmäßig abonniert.
project.ready: vollständig verarbeitet, bereit zum Prüfen oder Exportieren.
project.cancelled: Projekt abgebrochen.

Abonnements umfassen passende Videos Ihres Kontos aus Hauptanwendung, REST und MCP. Eigenständige Transcripts, gelöschte oder nicht mehr zugängliche Projekte sind ausgeschlossen. Ready bestätigt keine menschliche Prüfung.

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

data.resultUrl ist ein authentifizierter API-Endpunkt, kein Videodownload. Rufen Sie ihn mit Ihrem Leseschlüssel für frische Links ab. Ereignisse enthalten Metadaten, keine Videos oder Untertiteltexte.

Vor der Verarbeitung prüfen

Das Format folgt Standard Webhooks. Nutzen Sie einen kompatiblen Prüfer oder diese Schritte:

Bewahren Sie den Rohtext der Anfrage auf und lesen Sie webhook-id, webhook-timestamp und webhook-signature.
Entfernen Sie whsec_, decodieren Sie das Geheimnis als base64 und berechnen Sie HMAC-SHA256 über id.timestamp.rawBody. Vergleichen Sie die base64-Signatur in konstanter Zeit.
Verwerfen Sie vergangene oder zukünftige Zeitstempel außerhalb einer begrenzten Toleranz, etwa fünf Minuten. Bei Rotation sind mehrere leerzeichengetrennte v1,-Signaturen möglich; akzeptieren Sie einen Treffer mit einem vertrauenswürdigen Schlüssel.
Deduplizieren Sie nach Ereignis-ID und speichern Sie Arbeit vor der 2xx-Antwort. Verarbeiten Sie asynchron und bestätigen Sie innerhalb des 15-Sekunden-Limits.

Das Signaturgeheimnis ist vom API Key getrennt. Rotation zeigt das neue Geheimnis einmal und lässt 24 Stunden Überschneidung zu. Eine weitere Rotation ist währenddessen gesperrt.

Zustellungen testen und wiederholen

Der Einstellungstest sendet webhook.test; behandeln Sie ihn gesondert. Prüfen Sie den Verlauf der letzten 30 Tage, korrigieren Sie Empfängerfehler und wiederholen Sie fehlgeschlagene oder bereits zugestellte Ereignisse manuell.

Ereignisse können doppelt oder ungeordnet eintreffen. Bei Nicht-2xx-Antworten, Verbindungsfehlern oder fehlenden Bestätigungen gibt es insgesamt drei automatische Versuche: sofort sowie nach etwa einer und fünf Minuten. Nach dem dritten Fehler endet die automatische Zustellung. Manuelles Wiederholen behält die ID und startet wieder mit drei Versuchen; der Empfänger muss idempotent bleiben.

Deaktivieren stoppt ausstehende Zustellungen; laufende Anfragen können enden. Löschen des Ziels entfernt auch den Verlauf. Projektlöschung oder Zugriffsablauf stoppt dessen ausstehende Meldungen. Webhooks verlängern Medienzugriff nicht: sichern Sie rechtzeitig oder fragen Sie den Projektstatus ab.