Odbieraj powiadomienia o projektach

Utwórz odbiorcę

Po otwarciu dodaj publicznego odbiorcę HTTPS w Ustawienia → Integracje, wybierz zdarzenia i zachowaj sekret podpisu wyświetlany raz. Możesz też użyć klucza z 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"]}'

Zastąp URL prawdziwym adresem. Dozwolone jest tylko publiczne HTTPS na porcie 443, bez przekierowań. Localhost i sieci prywatne nie odbierają bezpośrednio.

Wybierz zdarzenia

project.completed: eksport gotowy; domyślnie wybrane.
project.failed: przetwarzanie lub eksport nie powiodły się; domyślnie wybrane.
project.ready: pełne przetwarzanie zakończone, gotowe do kontroli lub eksportu.
project.cancelled: projekt anulowany.

Dotyczy odpowiednich filmów konta utworzonych w aplikacji, REST i MCP. Wyklucza niezależne Transcripts, projekty usunięte lub poza terminem dostępu. Ready nie potwierdza sprawdzenia przez człowieka.

{
  "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 to uwierzytelniony endpoint, nie plik wideo. Użyj własnego API Key z odczytem, aby pobrać świeże linki. Zdarzenia zawierają metadane, nie film ani treść napisów.

Zweryfikuj przed przetwarzaniem

Format jest zgodny ze Standard Webhooks. Użyj zgodnego weryfikatora lub tych kontroli:

Zachowaj surowe body i odczytaj webhook-id, webhook-timestamp, webhook-signature.
Usuń whsec_, zdekoduj sekret base64 i oblicz HMAC-SHA256 z id.timestamp.rawBody. Porównaj podpis base64 w stałym czasie.
Odrzuć przeszłe i przyszłe znaczniki poza ograniczoną tolerancją, np. pięcioma minutami. Podczas rotacji może być wiele podpisów v1, rozdzielonych spacjami; zaakceptuj zgodny z zaufanym kluczem.
Usuwaj duplikaty według ID zdarzenia i utrwal pracę przed odpowiedzią 2xx. Przetwarzaj asynchronicznie, potwierdzając szybko w limicie 15 sekund.

Sekret podpisu jest osobny od API Key. Rotacja pokazuje nowy sekret raz i daje 24 godziny wspólnej ważności. Kolejna rotacja jest w tym czasie zablokowana.

Testuj i ponawiaj dostarczenia

Test w ustawieniach wysyła webhook.test; obsłuż go oddzielnie. Sprawdź historię ostatnich 30 dni, napraw odbiorcę i ponów ręcznie zdarzenie błędne lub już dostarczone.

Zdarzenia mogą się powtarzać i przychodzić poza kolejnością. Odpowiedź inna niż 2xx, błąd połączenia lub brak potwierdzenia uruchamiają łącznie trzy automatyczne próby: pierwszą od razu, a kolejne po około jednej i pięciu minutach. Trzeci błąd kończy automatyczne dostarczanie. Ręczna próba zachowuje ID i odnawia pełny limit trzech prób; odbiorca musi być idempotentny.

Wyłączenie zatrzymuje oczekujące dostarczenia; trwające żądanie może się zakończyć. Usunięcie odbiorcy usuwa historię. Usunięcie lub wygaśnięcie projektu zatrzymuje jego oczekujące powiadomienia. Webhooks nie wydłużają dostępu do plików: zapisuj na czas lub sprawdzaj stan projektu.