Request gövdesine webhook_url ekleyin
Desteklenen video bağlantılarında, parçalı yükleme kaydı açarken veya tek seferlik yüklemenin form alanında webhook_url gönderebilirsiniz. reuse_recent ile birlikte kullanılamaz. Önce webhook parametrelerine göz atın.
Webhook, ilk HTTP requesti bittikten sonra süren işler için uygundur: röportaj kayıtları, bölüm arşivi veya sosyal medya videolarının transkriptlerini toplama. Dönen transkripsiyon ID değerini kendi işlem kaydınızla birlikte saklayın; bildirimin hangi kullanıcı işlemine ait olduğunu bulabilmelisiniz.
Yönlendirme yapan bir adres yerine doğrudan son HTTPS endpointini verin. Adres oluşturma sırasında ve her gönderimde kontrol edilir. Geliştirme ortamında localhost alıcı olarak kullanılamaz. Aşağıdaki dosya yükleme örneğiyle kendi kaydınız üzerinden bildirim akışını deneyebilirsiniz.
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-F [email protected] \
-F webhook_url=https://example.com/hooks/transcript1Aynı bildirim ikinci kez gelirse işi tekrarlamayın
data alanı, metni içermeyen transkripsiyon nesnesidir. Tekrarlanan gönderimleri data.id ve type ikilisiyle ayırt edin. Tamamlanan transkripti ardından API üzerinden alın.
Aynı olayı birden fazla kez alabilecek şekilde tasarlayın. Requesti işlemiş olsanız bile yanıtınız 10 saniyeyi aşarsa tekrar gönderim yapılabilir. Yazı yayımlamak veya kullanıcıya haber vermek gibi işlemlerden önce transkripsiyon ID ve olay türünden oluşan benzersiz anahtarı kalıcı olarak kaydedin.
İmzayı doğruladıktan sonra olayı kalıcı biçimde kaydedin veya kuyruğa alın, hızlıca 2xx dönün. Transkripti data.id ile arka planda alın. transcription.failed gelirse data.error alanına bakıp kendi durumunuzu güncelleyin. İptal için bildirim gelmez; iptal akışınız kendi kaydını güncellemelidir.
X-Transcript1-Signature: t=<unix seconds>,v1=<hex digest>
{
"type": "transcription.completed",
"created_at": "2026-10-13T09:30:04.000Z",
"data": {
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"object": "transcription",
"status": "completed",
"transcript_source": "speech_to_text",
"billed_minutes": 4,
"error": null
}
}Webhook imza doğrulama için HMAC-SHA256 kullanın
t, nokta ve ham gövdeyi birleştirin; whsec_ anahtarınızla HMAC-SHA256 hesaplayın. İmzaları sabit zamanda karşılaştırın. Çok eski veya ileri tarihli zaman damgalarını reddedin. Tam adımlar imza doğrulama rehberinde bulunur.
JSON ayrıştırmadan önce gövdeyi geldiği haliyle okuyun. JSON verisini yeniden metne dönüştürmek boşlukları veya alan sırasını değiştirebilir; imza artık eşleşmez. Önce zaman damgasını ve header yapısını kontrol edin, eşit uzunluktaki imzaları sabit zamanda karşılaştırın. JSON gövdesini bundan sonra ayrıştırın.
Kısa örnek, t ve v1 değerlerinin daha önce ayrıştırılıp doğrulandığını varsayar. Dokümantasyonda 5 dakikalık zaman toleransı kullanan tam Node.js ve Python örnekleri vardır. Gizli anahtarı whsec_ öneki dahil kullanın. Ekip anahtarını yenilediğinizde sonraki gönderimler hemen yeni anahtarla imzalanır.
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex');
const valid = v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));Alıcınızı önce hata ve tekrar senaryolarıyla deneyin
Tamamlanmış işlem, başarısız işlem ve yinelenen bildirim göndererek test edin. Aynı tamamlanma bildirimi iki kez yayın başlatmamalı. Başarısız transkripsiyon da ortada metin yokken alma ve yayımlama akışına girmemeli. Hatalı imzayı reddetmeyi uygulama hatalarından ayrı test edin.
Her gönderimin zaman aşımı 10 saniyedir. Yanıt vermeden önce uzun indeksleme veya model çağrılarını beklemeyin. Olayı kalıcı kuyruğa aldıktan sonra yanıtlayın; sonraki işlemlerin tekrarını kendi kuyruğunuz yönetsin. Webhook gönderim takvimi, uygulamanızın iş kuyruğunun yerini tutmaz.
2xx dışındaki yanıtlar, bağlantı hataları ve zaman aşımı için 2, 4, 8, 16 ve 32 dakika sonra yeniden deneriz. Toplam 6 deneme yapılır; yönlendirmeler takip edilmez. İşlem ID, olay türü ve teslim durumunu loglayın. İmzalama anahtarını asla loglara yazmayın.
Denemeler bittiyse bilinen ID değerlerini transkripsiyon okuma endpointiyle karşılaştırın. ID değerini ilk oluşturma çağrısından itibaren saklayın. Eksik bildirimi araştırmak için medyayı yeniden göndermek zorunda kalmamalısınız.