Proje bildirimlerini alın

Alıcıyı hazırlayın

Video incelemeye hazır olduğunda, dışa aktarma bitince, proje başarısız veya iptal olunca Webhooks HTTP gönderir. Max aboneliklerinde kullanılabilir.

POST kabul eden herkese açık HTTPS URL gerekir, yalnız 443 desteklenir. Localhost ve özel ağlara doğrudan teslimat yoktur. Yönlendirmeler izlenmez. Yerel testte herkese açık HTTPS tüneli kullanın.

https://receiver.example/captionbolt yerine gerçek URL’nizi koyun.

Uç nokta ekleyin

1. Ayarlar → Entegrasyonlar açın.
2. HTTPS hedef URL’si ve olayları girin.
3. Webhook ekle seçin.
4. İmza anahtarını kaydedin; yalnız bir kez gösterilir.

Bu anahtar bildirimleri doğrular; API anahtarından farklıdır.

REST ile de oluşturabilirsiniz. API rehberine göre CAPTIONBOLT_API_KEY için webhooks:manage kullanın:

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

Yanıt id ve secret döndürür. Anahtarı alıcınızın ortamında güvenle saklayın.

Olayları seçin

| Olay | Anlam | | --- | --- | | project.ready | İşleme bitti; inceleme veya dışa aktarma mümkün | | project.completed | Çıktı bitti, sonuçlar alınabilir; varsayılan | | project.failed | İşleme veya dışa aktarma başarısız; varsayılan | | project.cancelled | Proje iptal edildi |

Web, REST veya MCP ile oluşturulan uygun video projeleri kapsanır. Yeni uç nokta sadece gelecek olayları alır; geçmiş değişiklikleri tekrarlamaz. Bağımsız Transcripts, silinmiş veya erişimi bitmiş projeler hariçtir.

project.ready video dışa aktarıldı veya insan tarafından incelendi anlamına gelmez.

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

Olaylar metadata içerir, video veya altyazı metni değil. data.resultUrl kimlik doğrulamalı REST uç noktasıdır. projects:read anahtarıyla yeni linkler alın; dosyaları anahtarsız indirin. İndirmelere bakın.

Gelen istekleri doğrulayın

CaptionBolt Standard Webhooks kullanır. Ayrıştırmadan veya işlem yapmadan önce değişmemiş ham gövde üzerinden imzayı doğrulayın. Başlıklar: webhook-id, webhook-timestamp, webhook-signature.

Node.js alıcı örneği

İmzayı doğrular, teslimat testi için ID ve tür kaydeder. Örnek Node.js 24 kullanır; başka dil de mümkündür. Kendi alıcı projenize JavaScript doğrulayıcıyı kurun:

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

receiver.mjs olarak kaydedin:

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

node receiver.mjs çalıştırıp /captionbolt yolunu HTTPS veya açık tünelden erişilebilir yapın. CaptionBolt yerel adrese değil, herkese açık HTTPS URL’ye erişmelidir.

Doğrulayıcı imza ve zaman damgasını kontrol eder; sunucu saati doğru olmalı. Önce JSON ayrıştırıp yeniden serileştirmeyin. İmza anahtarını veya tüm gövdeyi kaydetmeyin.

Üretimde günlük yerine kalıcı kabul kullanın: id ile tekilleştirin, 2xx öncesi olay veya görevi saklayıp asenkron işleyin. Saklama başarısızsa tekrar deneme için hata döndürün. Örnek yalnız alımı test eder; kalıcı kuyruk veya indirme sağlamaz.

Test gönderin

1. Alıcıyı başlatıp anahtarı ayarlayın.
2. Ayarlar → Entegrasyonlar altında uç noktayı açıp Test gönder seçin.
3. Teslimat geçmişi kontrol edin.
4. Doğrulanmış webhook.test kaydını onaylayın.

Uç nokta başına tek aktif test mümkündür. Bitmesini, ardından en az 60 saniye bekleyin. Elle tekrar denemelerin de bekleme süresi vardır; dönen aralığı uygulayın.

webhook.test ayrı işlenmelidir; tamamlanan video değildir. Sonuç alımını gerçek gelecek proje olayıyla test edin.

Başarısızsa URL, anahtar, ham gövde ve yanıtı inceleyin. 15 saniyede onaylayın. 2xx dışı, bağlantı hatası veya onay yokluğu tekrar denemeyi başlatır.

Tekrar denemeleri ve anahtarları yönetin

Bildirimler tekrarlı veya sırasız gelebilir. ID ile tekilleştirin, gerektiğinde mevcut durumu sorgulayın.

Üç otomatik deneme: ilk istek, ilk hatadan yaklaşık bir dakika, ikinci hatadan yaklaşık beş dakika sonra. Ardından durur. Alıcıyı düzeltip Yeniden gönder seçin: aynı ID ile üç yeni deneme. Geçmiş 30 gün tutulur.

Gizli anahtarı yenile ile yenileyin, yeni anahtarı saklayıp alıcıyı güncelleyin. Eski anahtar 24 saat geçerli; bu sürede iki imza gönderilir. Süre bitmeden başka yenileme engellenir.

Devre dışı bırakmak bekleyen teslimatları durdurur; sürmekte olan istek bitebilir. Silmek geçmişi de kaldırır. Proje silinmesi veya erişim bitişi bekleyen bildirimleri durdurur. Webhooks 14 günü uzatmaz; sonuçları önceden alıp saklayın.