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
- Ham istek gövdesini okuyun — size POST ettiğimiz baytların tam hâlini.
hmac_sha256(secret, body).hexdigest()hesaplayın.X-ThunderPhone-Signatureile sabit zamanda karşılaştırın. (Basit dize karşılaştırması zamanlama bilgilerini sızdırır.)
, 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.
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 birendpoint 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.
verify() yardımcısı, iki farkla değişmeden çalışır:
GET/DELETEaraçlarının gövdesi yoktur. Bağımsız değişkenler sorgu parametreleri olarak iletilir ve imza boş bayt dizisi üzerinden hesaplanır — yaniverify(b"", sig, secret)(Python) veyaverify(Buffer.alloc(0), sig, secret)(Node). Sorgu dizesini karmalamayın.- Eski webhook yapılandırması olmayan kuruluşların kuruluş gizli anahtarı yoktur.
Bu durumda araç çağrıları yalnızca
X-ThunderPhone-Call-IDtaşı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.
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
Varsayılan biçimlendirmeyle yeniden serileştirme
Varsayılan biçimlendirmeyle yeniden serileştirme
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.Çerçeve JSON'u otomatik ayrıştırıyor
Çerçeve JSON'u otomatik ayrıştırıyor
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.Zamanlama açısından güvenli olmayan karşılaştırma
Zamanlama açısından güvenli olmayan karşılaştırma
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.Araç uç noktaları için yanlış gizli anahtar
Araç uç noktaları için yanlış gizli anahtar
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.GET/DELETE araçlarında sorgu dizesini karma işlemeden geçirmek
GET/DELETE araçlarında sorgu dizesini karma işlemeden geçirmek
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.
Eşleşme olmadığında 401 döndürmemek
Eşleşme olmadığında 401 döndürmemek
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.