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.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 dengandata, 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:
Verifikasi tanda tangan
Setiap permintaan membawa tanda tangan HMAC-SHA256 atas body permintaan mentah dalam headerX-ThunderPhone-Signature. Kunci penandatanganan adalah
secret endpoint (atau secret webhook tingkat organisasi Anda untuk
pengiriman lama).
Langkah
- Baca body permintaan mentah sebelum parsing apa pun.
- Hitung
hmac_sha256(secret, body).hexdigest(). - Bandingkan dalam waktu konstan dengan header
X-ThunderPhone-Signature.
Semantik pengiriman
Semantik ini berlaku untuk pengiriman endpoint. Webhook URL tunggal legacy adalah satu percobaan sinkron tanpa percobaan ulang.Percobaan ulang
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
Urutan
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.Duplikat
Duplikat
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.Waktu habis
Waktu habis
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.IP sumber
IP sumber
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.