Skip to main content
ThunderPhone mengirim permintaan HTTP POST ke server Anda ketika sesuatu terjadi selama panggilan — panggilan masuk dimulai, panggilan berakhir, proses penilaian selesai, peringatan dipicu, dan sebagainya. Ada dua model pengiriman:

Endpoint webhook (direkomendasikan)

Beberapa URL, secret per endpoint, filter peristiwa per endpoint, dan percobaan ulang otomatis. Kelola melalui GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.

Webhook legacy satu URL

Satu URL per organisasi. Membawa peristiwa siklus hidup panggilan, termasuk pertukaran konfigurasi yang memblokir. Dikelola di GET/PUT /v1/webhook.
Kesepuluh jenis peristiwa dalam katalog peristiwa dikirim melalui endpoint webhook. Enam peristiwa siklus hidup panggilan (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) juga dikirim ke webhook legacy satu URL — jika Anda memiliki URL legacy dan endpoint yang cocok, Anda menerima peristiwa pada kedua jalur. Perilaku pemblokiran ( pertukaran konfigurasi telephony.incoming / web.incoming dan pengiriman tool mode webhook) hanya tersedia pada jalur legacy; setiap pengiriman endpoint adalah notifikasi fire-and-forget.

Format payload

Pengiriman endpoint berupa objek JSON dengan data, event_id, dan type:
event_id unik untuk setiap peristiwa yang dipancarkan. Nilainya identik di seluruh percobaan ulang dan di setiap endpoint yang menerima peristiwa — lakukan deduplikasi berdasarkan nilai tersebut. Webhook legacy satu URL mengirim type dan data yang sama, tetapi tanpa event_id:
Dalam transmisi, setiap body diserialisasi secara kanonis — kunci diurutkan secara alfabetis, tanpa spasi, UTF-8. Contoh yang dicetak rapi dalam dokumentasi ini hanya untuk keterbacaan. Lihat Katalog peristiwa untuk daftar lengkap jenis peristiwa dan field payload.

Verifikasi tanda tangan

Setiap permintaan membawa tanda tangan HMAC-SHA256 atas body permintaan mentah dalam header X-ThunderPhone-Signature. Kunci penandatanganan adalah secret endpoint (atau secret webhook tingkat organisasi Anda untuk pengiriman lama).

Langkah

  1. Baca body permintaan mentah sebelum parsing apa pun.
  2. Hitung hmac_sha256(secret, body).hexdigest().
  3. Bandingkan dalam waktu konstan dengan header X-ThunderPhone-Signature.
Kami menandatangani byte yang tepat kami kirimkan, dan byte tersebut adalah serialisasi JSON kanonis (kunci diurutkan, pemisah ringkas). Jadi, memverifikasi terhadap body mentah selalu berfungsi — dan jika framework Anda hanya memberikan JSON yang telah diurai, menserialisasikannya kembali dengan kunci yang diurutkan dan pemisah ringkas menghasilkan byte yang identik. Kedua metode dibahas dalam panduan verifikasi.

Semantik pengiriman

Semantik ini berlaku untuk pengiriman endpoint. Webhook URL tunggal legacy adalah satu percobaan sinkron tanpa percobaan ulang.
Setiap event langsung dicoba sekali. Respons 2xx apa pun mengakui pengiriman. Untuk hasil lainnya (non-2xx, kesalahan koneksi, waktu habis), kami mencoba ulang pada 1 m, 5 m, 30 m, 2 h, 6 h, 12 h, dan 24 h setelah percobaan pertama — 8 percobaan selama 24 jam. Jika setiap percobaan gagal, pengiriman berhenti dan endpoint ditandai sebagai status="failing" di endpoint webhook. Kembalikan 2xx segera setelah payload diterima dan disimpan secara andal; proses secara asinkron.
Urutan pengiriman bersifat best-effort. Dalam praktiknya, kami mengirimkan sesuai urutan event dipancarkan, tetapi percobaan ulang dapat mengubah urutan saat terjadi kegagalan. Selalu lakukan deduplikasi dan rekonsiliasi berdasarkan call_id / id objek.
Pengiriman bersifat at-least-once: percobaan ulang setelah respons yang tidak pernah kami terima dapat menduplikasi event. Setiap percobaan ulang membawa event_id yang sama, jadi simpan id yang telah diproses dan lewati pengulangan. event_id juga dibagikan di seluruh endpoint — dua endpoint yang berlangganan pada event yang sama menerima event_id yang sama.
Pengiriman endpoint memiliki waktu habis 30 s per percobaan. Pada jalur legacy, permintaan pemblokiran yang mengatur perilaku panggilan langsung — pertukaran konfigurasi telephony.incoming / web.incoming — akan mengalami waktu habis setelah 10 s, tetapi respons yang lambat menunda penerimaan panggilan, jadi usahakan menjawab dalam beberapa detik. Dispatch tool mode webhook memungkinkan 20 s.
Webhook keluar berasal dari rentang IP cloud ThunderPhone. Jika firewall Anda memerlukan allowlist, hubungi dukungan dan kami akan membagikan rentang saat ini.

Memilih antara webhook legacy dan berbasis endpoint

Integrasi baru harus menerima event melalui webhook berbasis endpoint. Pertahankan (atau tambahkan) URL legacy hanya jika Anda mengonfigurasi panggilan secara dinamis saat panggilan diangkat atau menggunakan dispatch tool mode webhook — pertukaran permintaan/respons tersebut hanya berjalan pada jalur legacy.

Terkait

Katalog event

Semua jenis event dan payload-nya.

Endpoint webhook

Kelola beberapa endpoint, filter event, dan secret.

telephony.incoming / web.incoming

Permintaan pemblokiran yang harus dijawab server Anda untuk mengonfigurasi panggilan.

telephony.complete / web.complete

Payload pascapanggilan dengan transkrip, rekaman, dan metrik.