Skip to main content
ThunderPhone, çağrı sırasında gerçekleşen durumlarda sunucunuza HTTP POST istekleri gönderir — gelen bir çağrı başladığında, çağrı sona erdiğinde, bir değerlendirme çalışması tamamlandığında, bir uyarı tetiklendiğinde vb. İki teslimat modeli vardır:

Webhook uç noktaları (önerilir)

Birden fazla URL, uç nokta başına gizli anahtarlar, uç nokta başına olay filtreleri ve otomatik yeniden denemeler. GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints üzerinden yönetin.

Tek URL eski webhook

Kuruluş başına bir URL. Engelleyici yapılandırma alışverişleri dahil olmak üzere çağrı yaşam döngüsü olaylarını taşır. GET/PUT /v1/webhook üzerinden yönetilir.
Olay kataloğundaki on olay türünün tümü webhook uç noktaları aracılığıyla teslim edilir. Altı çağrı yaşam döngüsü olayı (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) ayrıca eski tek URL webhook’una da gönderilir — hem eski bir URL’niz hem de eşleşen bir uç noktanız varsa, olayı her iki yolda da alırsınız. Engelleyici davranış (telephony.incoming / web.incoming yapılandırma alışverişi ve webhook modunda araç yönlendirme) yalnızca eski yolda bulunur; her uç nokta teslimatı gönder ve unut bildirimidir.

Yük biçimi

Uç nokta teslimatları data, event_id ve type içeren bir JSON nesnesidir:
event_id, yayınlanan her olay için benzersizdir. Yeniden denemelerde ve olayı alan her uç noktada aynıdır — bunun üzerinden yinelenenleri ayıklayın. Eski tek URL webhook’u aynı type ve data değerlerini gönderir, ancak event_id olmadan:
İletim sırasında her gövde kanonik olarak serileştirilir — anahtarlar alfabetik olarak sıralanır, boşluk içermez ve UTF-8 kullanılır. Bu dokümanlardaki biçimlendirilmiş örnekler yalnızca okunabilirlik içindir. Olay türlerinin ve yük alanlarının tam listesi için Olay kataloğuna bakın.

İmza doğrulama

Her istek, X-ThunderPhone-Signature başlığında ham istek gövdesi üzerinden oluşturulmuş bir HMAC-SHA256 imzası taşır. İmzalama anahtarı, uç noktanın secret değeridir (veya eski teslimatlar için kuruluş düzeyindeki webhook secret değerinizdir).

Adımlar

  1. Herhangi bir ayrıştırma işleminden önce ham istek gövdesini okuyun.
  2. hmac_sha256(secret, body).hexdigest() hesaplayın.
  3. Sabit zamanda X-ThunderPhone-Signature başlığıyla karşılaştırın.
İlettiğimiz baytları tam olarak imzalarız ve bu baytlar kanonik JSON serileştirmesidir (sıralı anahtarlar, sıkıştırılmış ayırıcılar). Bu nedenle ham gövdeye göre doğrulama her zaman çalışır — çerçeveniz size yalnızca ayrıştırılmış JSON veriyorsa, bunu sıralı anahtarlar ve sıkıştırılmış ayırıcılarla yeniden serileştirmek aynı baytları üretir. Her iki yöntem de doğrulama kılavuzunda açıklanmıştır.

Teslimat semantiği

Bu semantik, uç nokta teslimatları için geçerlidir. Eski tek URL’li webhook, yeniden denemesi olmayan tek bir eşzamanlı denemedir.
Her olay hemen bir kez denenir. Herhangi bir 2xx yanıtı teslimatı onaylar. Diğer tüm sonuçlarda (2xx olmayan yanıt, bağlantı hatası, zaman aşımı), ilk denemeden 1 dk, 5 dk, 30 dk, 2 sa, 6 sa, 12 sa ve 24 sa sonra yeniden deneriz — 24 saate yayılan 8 deneme. Her deneme başarısız olursa teslimat durur ve uç nokta, webhook uç noktalarında status="failing" olarak işaretlenir. Yük kalıcı olarak kabul edilir edilmez 2xx döndürün; eşzamansız olarak işleyin.
Teslimat sıralaması en iyi çabaya dayanır. Uygulamada olayları yayımlandıkları sırayla teslim ederiz, ancak yeniden denemeler başarısızlık durumunda sıralamayı değiştirebilir. Her zaman call_id / nesne kimliğine göre yinelenenleri kaldırın ve mutabakat sağlayın.
Teslimat en az bir kez gerçekleştirilir: hiç görmediğimiz bir yanıttan sonraki yeniden deneme bir olayı yineleyebilir. Her yeniden deneme aynı event_id değerini taşır; bu nedenle işlenen kimlikleri saklayın ve tekrarları atlayın. event_id ayrıca uç noktalar arasında da paylaşılır — aynı olaya abone olan iki uç nokta aynı event_id değerini alır.
Uç nokta teslimatlarında deneme başına 30 sn zaman aşımı vardır. Eski yolda, canlı çağrı davranışını yönlendiren engelleyici istekler — telephony.incoming / web.incoming yapılandırma alışverişi — 10 sn sonra zaman aşımına uğrar; ancak yavaş bir yanıt çağrının cevaplanmasını geciktirir, bu nedenle birkaç saniye içinde yanıt vermeyi hedefleyin. Webhook modundaki araç yönlendirme 20 sn süre tanır.
Giden webhook’lar ThunderPhone’un bulut IP aralığından kaynaklanır. Güvenlik duvarınız bir izin listesi gerektiriyorsa destek ekibiyle iletişime geçin; güncel aralıkları paylaşırız.

Eski ve uç nokta tabanlı webhook’lar arasında seçim yapma

Yeni entegrasyonlar, olayları uç nokta tabanlı webhook’lar üzerinden tüketmelidir. Yalnızca çağrıları cevaplama sırasında dinamik olarak yapılandırıyorsanız veya webhook modunda araç yönlendirme kullanıyorsanız eski bir URL’yi koruyun (veya ekleyin) — bu istek/yanıt alışverişleri yalnızca eski yolda çalışır.

İlgili

Olay kataloğu

Tüm olay türleri ve yükleri.

Webhook uç noktaları

Birden çok uç noktayı, olay filtrelerini ve gizli anahtarları yönetin.

telephony.incoming / web.incoming

Çağrıları yapılandırmak için sunucunuzun yanıtlaması gereken engelleyici istek.

telephony.complete / web.complete

Transkript, kayıt ve metrikleri içeren çağrı sonrası yük.