Odbieraj powiadomienia projektów

Przygotuj odbiornik

Webhooks wysyłają HTTP, gdy film jest gotowy do sprawdzenia, eksport kończy się lub projekt zawodzi albo jest anulowany. Dostępne w subskrypcjach Max.

Potrzebny publiczny URL HTTPS dla POST, tylko port 443. Localhost i sieci prywatne nie odbierają bezpośrednio. CaptionBolt nie śledzi przekierowań; lokalnie użyj publicznego tunelu HTTPS.

Zastąp https://receiver.example/captionbolt prawdziwym adresem.

Dodaj endpoint

1. Otwórz Ustawienia → Integracje.
2. Podaj Docelowy adres HTTPS i wybierz zdarzenia.
3. Wybierz Dodaj Webhook.
4. Zapisz sekret podpisu; pokazuje się raz.

Sekret służy do weryfikacji i różni się od klucza API.

Możesz też tworzyć przez REST. Ustaw CAPTIONBOLT_API_KEY z webhooks:manage według przewodnika API:

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

Odpowiedź zwraca id i secret. Zachowaj sekret bezpiecznie w środowisku odbiornika.

Wybierz zdarzenia

| Zdarzenie | Znaczenie | | --- | --- | | project.ready | Przetwarzanie ukończone; sprawdzenie lub eksport możliwy | | project.completed | Eksport ukończony, wyniki dostępne; domyślnie zaznaczone | | project.failed | Błąd przetwarzania lub eksportu; domyślnie zaznaczone | | project.cancelled | Projekt anulowany |

Obejmują odpowiednie projekty wideo konta ze strony, REST lub MCP. Nowy endpoint otrzymuje przyszłe zdarzenia, nie odtwarza historii. Osobne Transcripts, usunięte lub wygasłe projekty są wykluczone.

project.ready nie znaczy wyeksportowany lub sprawdzony przez człowieka.

{
  "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"
  }
}

Zdarzenia zawierają metadane, nie film ani tekst napisów. data.resultUrl wymaga autoryzacji REST. Pobierz nowe linki kluczem projects:read, a pliki bez klucza. Zobacz pobieranie.

Weryfikuj przychodzące żądania

CaptionBolt używa Standard Webhooks. Sprawdź podpis na dokładnym surowym body przed analizą lub działaniem. Nagłówki: webhook-id, webhook-timestamp, webhook-signature.

Przykład odbiornika Node.js

Weryfikuje podpisy i zapisuje ID i typ do testów. Przykład używa Node.js 24; inny język też jest możliwy. Zainstaluj weryfikator JavaScript we własnym projekcie odbiornika:

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

Zapisz jako 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");

Uruchom node receiver.mjs i udostępnij /captionbolt przez HTTPS lub tunel publiczny. CaptionBolt musi osiągnąć publiczny URL HTTPS, nie lokalny adres.

Weryfikator sprawdza podpis i czas; zegar musi być poprawny. Nie analizuj i nie serializuj ponownie JSON przed weryfikacją. Nie zapisuj sekretu ani całego body.

W produkcji zastąp logowanie trwałym przyjęciem: deduplikuj po id, zapisz zdarzenie lub zadanie przed 2xx i przetwarzaj asynchronicznie. Przy błędzie zapisu zwróć błąd dla ponowienia. Przykład testuje tylko odbiór, bez trwałej kolejki i pobierania.

Wyślij test

1. Uruchom odbiornik i ustaw sekret.
2. Otwórz endpoint w Ustawienia → Integracje, wybierz Wyślij test.
3. Sprawdź Historię dostarczeń.
4. Potwierdź zweryfikowane webhook.test w logu.

Jeden aktywny test na endpoint. Poczekaj na zakończenie i potem co najmniej 60 sekund. Ręczne ponowienia także mają czas oczekiwania; przestrzegaj zwróconego interwału.

Obsługuj webhook.test osobno; nie reprezentuje gotowego filmu. Testuj wyniki przyszłym rzeczywistym zdarzeniem.

Przy błędzie sprawdź URL, sekret, body i odpowiedź. Potwierdź w 15 sekund. Nie-2xx, błędy połączenia lub brak potwierdzenia powodują ponowienia.

Zarządzaj ponowieniami i sekretami

Powiadomienia mogą się powtarzać lub przychodzić poza kolejnością. Deduplikuj po ID i sprawdzaj aktualny stan, gdy potrzebny.

Trzy próby automatyczne: pierwsza, około minuty po pierwszym błędzie i pięć minut po drugim. Potem automat się zatrzymuje. Napraw i wybierz Ponów dostarczenie: ten sam ID, trzy nowe próby. Historia trwa 30 dni.

Wybierz Zmień sekret, zapisz nowy sekret i zaktualizuj odbiornik. Stary jest ważny 24 godziny; oba podpisy są dołączane w tym okresie. Kolejna rotacja jest zablokowana do końca.

Wyłączenie zatrzymuje oczekujące dostarczenia; trwające żądanie może się skończyć. Usunięcie usuwa historię. Usunięcie lub wygaśnięcie projektu zatrzymuje jego oczekujące powiadomienia. Webhooks nie wydłużają 14 dni; pobierz i zapisz wyniki wcześniej.