# Webhook transkripsi untuk memberi kabar saat proses berakhir

> Pasang webhook transkripsi lewat webhook_url. Terima POST bertanda tangan saat proses selesai atau gagal, tanpa polling status dari aplikasi Anda.

Canonical: https://transcript1.com/id/features/webhook-transkripsi
Language: id
Last updated: 2026-10-19

Webhook transkripsi mengirim POST bertanda tangan ke aplikasi Anda ketika transkripsi selesai atau gagal. Sertakan webhook_url saat membuat transkripsi, lalu tunggu event alih-alih memeriksa status berulang kali.

- Event transcription.completed dan transcription.failed
- Tanda tangan HMAC-SHA256 pada setiap pengiriman
- Hingga 6 percobaan dengan jeda yang bertambah

## Terima event, lalu ambil transkripnya

### Selesai atau gagal

Anda mendapat transcription.completed atau transcription.failed. Transkripsi yang dibatalkan tidak mengirim webhook.

### Periksa pengirim lewat tanda tangan

Header X-Transcript1-Signature memuat timestamp dan HMAC-SHA256 atas body mentah. Kuncinya adalah secret tim Anda yang berawalan whsec_.

### Pengiriman gagal akan dicoba lagi

Respons 2xx menandakan event diterima. Jika gagal, kami mencoba lagi setelah jeda 2, 4, 8, 16 dan 32 menit, hingga 6 percobaan total.

### Endpoint harus bisa diakses publik

URL wajib memakai HTTPS dan mengarah ke alamat publik. Kami memeriksanya saat transkripsi dibuat dan pada setiap pengiriman.

### Payload tanpa isi transkrip

Event memuat objek transkripsi tanpa teksnya. Gunakan ID dari event untuk mengambil transkrip dalam format yang Anda perlukan.

## 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](https://transcript1.com/id/docs/webhooks#set-a-webhook-url) 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.

### Unggah file dengan webhook penyelesaian

```
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@episode.mp3 \
  -F webhook_url=https://example.com/hooks/transcript1
```

## Catat 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](https://transcript1.com/id/docs/api-reference#get-a-transcription).

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.

### POST yang diterima endpoint Anda

```
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](https://transcript1.com/id/docs/webhooks#verify-the-signature) 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.

### Node.js

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

- [Contoh verifikasi webhook lengkap](https://transcript1.com/id/docs/webhooks)

## 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](https://transcript1.com/id/docs/api-reference#get-a-transcription). Callback jangan menjadi satu-satunya catatan bahwa transkripsi pernah dibuat. Dengan ID sejak awal, notifikasi yang hilang bisa diperiksa tanpa mengirim ulang rekaman.

## Pertanyaan umum

### Di mana saya menemukan signing secret?

Buka halaman “Webhooks” di dasbor. Secret berawalan whsec_ berlaku untuk tim Anda dan bisa dirotasi di sana kapan saja.

### Kalau endpoint saya sedang gagal, apa yang terjadi?

Kami mencoba lagi dengan jeda yang makin panjang, hingga 6 percobaan selama sekitar satu jam. Tiap percobaan punya timeout 10 detik. Redirect tidak diikuti.

### Webhook bisa dipakai lewat MCP?

Tidak. Webhook hanya tersedia lewat REST API. Tool MCP menunggu transkrip atau mengembalikan ID agar asisten bisa membacanya lagi nanti.

## Halaman terkait

- [Notifikasi webhook (dokumentasi)](https://transcript1.com/id/docs/webhooks)
- [API transkripsi file](https://transcript1.com/id/features/speech-to-text-api)
- [Agen AI dan LLM](https://transcript1.com/id/use-cases/transkrip-untuk-agen-ai)