Skip to main content
Sunucunuza gönderdiğimiz her istek — webhook teslimatları ve araç uç noktası çağrıları — X-ThunderPhone-Signature başlığında bir HMAC-SHA256 imzası taşır. Doğrulamayı bir kez doğru şekilde uygulayın ve aynı yardımcıyı her işleyiciye ekleyin.

Algoritma

  1. Ham istek gövdesini okuyun — size POST ettiğimiz baytların tam hâlini.
  2. hmac_sha256(secret, body).hexdigest() hesaplayın.
  3. X-ThunderPhone-Signature ile sabit zamanda karşılaştırın. (Basit dize karşılaştırması zamanlama bilgilerini sızdırır.)
İlettiğimiz baytların tam olarak kendisini imzalarız; bu nedenle ham gövdeyi doğrulamak her zaman çalışır. Bu baytlar aynı zamanda yükün kanonik JSON serileştirmesidir — anahtarlar alfabetik olarak sıralanır, ayırıcılar sıkıştırılır (boşluksuz , ve :), UTF-8 kullanılır. Bu, çerçeveniz yalnızca ayrıştırılmış JSON’u sunduğunda size ikinci ve tamamen eşdeğer bir yöntem sağlar: kanonik olarak yeniden serileştirin ve bunun HMAC’ini hesaplayın.
Ham gövdeyi tercih edin — bir adım daha azdır ve bazı dillerdeki JSON sayı gidiş-dönüş dönüştürme tuhaflıklarına karşı dayanıklıdır.

Hangi gizli anahtar?

Gizli anahtarı gizli anahtar yöneticinizde veya ortam değişkeninde saklayın — asla commit etmeyin.

Referans uygulamalar

Dördü de ham istek gövdesini doğrular:

Çerçeveye özgü entegrasyon

Araç çağrılarını doğrulama

Ajan, fonksiyon araçlarınızdan birini doğrudan çağırdığında (aracın bir endpoint değeri olduğunda), istek, yapılandırdığınız endpoint.headers ile birlikte iki ThunderPhone başlığı taşır:
  • X-ThunderPhone-Call-ID — canlı çağrının sayısal kimliği.
  • X-ThunderPhone-Signature — tam istek gövdesi baytları üzerinden, kuruluş düzeyindeki webhook gizli anahtarınız ile anahtarlanmış HMAC-SHA256.
Aynı verify() yardımcısı, iki farkla değişmeden çalışır:
  1. GET / DELETE araçlarının gövdesi yoktur. Bağımsız değişkenler sorgu parametreleri olarak iletilir ve imza boş bayt dizisi üzerinden hesaplanır — yani verify(b"", sig, secret) (Python) veya verify(Buffer.alloc(0), sig, secret) (Node). Sorgu dizesini karmalamayın.
  2. Eski webhook yapılandırması olmayan kuruluşların kuruluş gizli anahtarı yoktur. Bu durumda araç çağrıları yalnızca X-ThunderPhone-Call-ID taşır ve imza başlığı içermez. İmzalama gizli anahtarı almak için eski webhook’u (PUT /v1/webhook) yapılandırın veya araç çağrılarını endpoint.headers üzerinden kendi başlığınızla doğrulayın.
Webhook-modu araç yönlendirmesi (endpoint değeri olmayan, kuruluş webhook’unuza telephony.tool / web.tool olarak iletilen araçlar) normal imzalı bir webhook’tur — yukarıdaki standart yöntem geçerlidir. Her iki istek biçimi için Fonksiyon Araçları sayfasına bakın.

Yaygın sorunlar

Gövdeyi ayrıştırıp JSON kitaplığınızın varsayılanlarıyla yeniden dışa aktarmak (, / : sonrasında boşluklar, ekleme sırasına göre anahtarlar) farklı baytlar üretir ve HMAC’i bozar. Ham gövdeyi doğrulayın — veya yeniden serileştirmeniz gerekiyorsa kanonik biçimimizle tam olarak eşleşin: sıralanmış anahtarlar, sıkıştırılmış ayırıcılar, UTF-8.
Express’in express.json() ara yazılımı gövde akışını tüketir ve ham baytları kaybedersiniz. Webhook rotasında özellikle express.raw() kullanın veya ham gövdeyi bir ön ara yazılımda arabelleğe alın. NestJS / Koa için de durum aynıdır — “raw body” belgelerini inceleyin.
JS’de expected === signature veya Python’da expected == signature zamanlamaya bağlı karşılaştırmalardır. Sırasıyla crypto.timingSafeEqual veya hmac.compare_digest kullanın. Performans farkı yok denecek kadar azdır.
Doğrudan araç uç noktası çağrıları, kuruluş düzeyindeki webhook gizli anahtarı (GET /v1/webhook) ile imzalanır — /v1/developer/webhook-endpoints içindeki uç noktaya özel herhangi bir gizli anahtarla değil. Aynı verify() işlevini yeniden kullanın, ancak araç rotalarında kuruluş gizli anahtarını verdiğinizden emin olun.
Gövdesi olmayan araç yöntemlerinde imza, boş bayt dizesini kapsar ve tek bir evrensel yaklaşım korunur: ne olursa olsun ham istek gövdesine HMAC uygulayın. URL’yi veya sorgu dizesini karma işlemden geçirmek hiçbir zaman eşleşmez.
Doğrulama başarısız olduğunda 200 döndürmek, işleyiciyi bir yeniden oynatma hedefi hâline getirir. Doğrulama başarısız olursa her zaman 2xx dışında yanıt verin.

Sonraki adımlar

Webhook genel bakışı

Teslimat anlambilimi, yeniden denemeler, kaynak IP’ler.

Webhook uç noktaları

Birden fazla URL’yi yönetin, gizli anahtarları döndürün.

İşlev Araçları

İki araç çağırma yolu ve istek biçimleri.

Araç entegrasyonları

Araç destekli eksiksiz bir entegrasyonu uçtan uca oluşturun.