Tambahkan webhook_url ke request Anda
Kirim webhook_url bersama link video atau reservasi unggahan per bagian. Untuk unggahan satu request, gunakan field form. Opsi ini tidak bisa digabung dengan reuse_recent. Periksa parameter webhook sebelum menambahkannya.
Gunakan webhook untuk pekerjaan yang berlanjut setelah request awal berakhir, seperti memproses wawancara, membuat arsip episode atau mengumpulkan teks dari daftar video. Simpan ID transkripsi bersama catatan pekerjaan Anda agar callback bisa dikaitkan dengan tindakan pengguna yang tepat.
Pakai URL HTTPS publik yang langsung menuju handler akhir. Redirect tidak diikuti, dan localhost tidak bisa menjadi penerima. Contoh di bawah memakai unggahan file agar Anda bisa menguji alurnya dengan rekaman sendiri.
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/transcript1Catat event sebelum menjalankan pekerjaan lanjutan
data berisi objek transkripsi tanpa isi transkrip. Gunakan pasangan data.id dan type untuk mengenali pengiriman ganda. Setelah event selesai diterima, ambil transkrip lewat API.
Handler harus siap menerima event yang sama lebih dari sekali. Request bisa sudah Anda proses tetapi tetap diulang jika respons melewati batas 10 detik. Setelah tanda tangan valid, simpan event secara persisten atau masukkan ke antrean, lalu segera balas 2xx. Catat kunci deduplikasi sebelum menerbitkan artikel atau mengirim notifikasi agar tindakan itu tidak terjadi dua kali.
Ambil teks dengan data.id melalui pekerjaan latar belakang. Untuk transcription.failed, baca data.error dan perbarui status di aplikasi Anda. Karena pembatalan tidak mengirim callback, alur pembatalan Anda harus memperbarui statusnya sendiri.
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
}
}Verifikasi tanda tangan webhook HMAC sebelum membaca JSON
Hitung HMAC-SHA256 atas t + titik + body mentah memakai secret whsec_ tim Anda. Bandingkan secara constant-time dan tolak timestamp yang terlalu jauh dari waktu sekarang. Ikuti panduan verifikasi lengkap untuk validasi headernya.
Baca byte body persis seperti yang diterima, sebelum JSON parser mengubahnya. Mengubah objek JSON kembali menjadi teks bisa mengganti spasi atau urutan key sehingga tanda tangan tidak cocok. Validasi timestamp dan header, pastikan panjang digest sama, bandingkan secara constant-time, baru parse JSON.
Contoh singkat berikut menganggap t dan v1 sudah diekstrak serta divalidasi. Dokumentasi menyediakan contoh Node.js dan Python lengkap dengan toleransi timestamp 5 menit. Pakai seluruh secret termasuk awalan whsec_. Jika secret tim dirotasi, pengiriman berikutnya langsung memakai secret baru.
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));Uji event gagal dan pengiriman ganda juga
Uji event selesai, event gagal dan event yang dikirim dua kali. Pastikan satu transkripsi selesai tidak menerbitkan konten berulang, dan kegagalan tidak memicu alur yang mengharapkan teks. Uji penolakan tanda tangan secara terpisah dari error pemrosesan aplikasi.
Setiap pengiriman punya batas waktu 10 detik. Jangan menahan respons sambil menunggu pengindeksan atau pekerjaan model. Setelah event dicatat dan Anda membalas, antrean persisten milik aplikasi Anda yang menangani percobaan ulang pekerjaan lanjutan.
Respons selain 2xx, error koneksi atau timeout memicu percobaan ulang dengan jeda 2, 4, 8, 16 dan 32 menit. Totalnya paling banyak 6 percobaan. Redirect tidak diikuti. Catat ID, jenis event dan status pengiriman untuk membedakan masalah penerima dari masalah transkripsi. Jangan mencatat signing secret.
Jika semua percobaan habis, cocokkan ID yang sudah Anda simpan dengan status transkripsi di API. Callback jangan menjadi satu-satunya catatan bahwa transkripsi pernah dibuat. Dengan ID sejak awal, notifikasi yang hilang bisa diperiksa tanpa mengirim ulang rekaman.