Webhook

ThunderPhone

ThunderPhone, bir çağrı sırasında gerçekleşen olaylarda — gelen çağrının başlaması, çağrının bitmesi, bir değerlendirme çalışmasının tamamlanması, bir uyarının tetiklenmesi vb. — sunucunuza HTTP POST istekleri gönderir. İki teslim modeli vardır:

Olay kataloğunda listelenen tüm olay türleri webhook uç noktaları üzerinden 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'li webhook'a 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. Bloklayıcı davranış ( telephony.incoming / web.incoming yapılandırma alışverişi ve webhook modu araç yönlendirmesi) yalnızca eski yolda bulunur; her uç nokta teslimi, yanıt beklemeden gönderilen bir bildirimdir.

Yük biçimi#

Uç nokta teslimleri data, event_id ve type içeren bir JSON nesnesidir:

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

event_id, yayımlanan her olay için benzersizdir. Yeniden denemelerde ve olayı alan her uç noktada aynıdır — tekilleştirme için bunu kullanın.

Eski tek URL'li webhook aynı type ve data değerlerini ancak event_id olmadan gönderir:

{
  "type": "telephony.incoming",
  "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" }
}

Aktarım sırasında her gövde kanonik olarak serileştirilir — anahtarlar alfabetik olarak sıralanır, boşluk kullanılmaz, UTF-8 kullanılır. Bu belgelerdeki okunabilir biçimlendirilmiş örnekler yalnızca okunabilirlik içindir.

Olay türleri ve yük alanlarının tam listesi için Olaylar kataloğuna bakın.

İmza doğrulama#

Her istek, ikisi de uç noktanın secret anahtarıyla (veya eski teslimatlar için kuruluş düzeyindeki webhook secret anahtarınızla) HMAC-SHA256 kullanılarak oluşturulmuş iki imza taşır:

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex>, zaman damgasını, yöntemi, yolu ve sorguyu ve ham gövdeyi imzalar. Bunu doğrulayın ve yakalanmış bir isteğin daha sonra yeniden oynatılmasını önlemek için t değeri saatinizden 5 dakikadan fazla farklı olan istekleri reddedin. Yeniden denemeler gönderildiklerinde yeniden imzalanır.
• X-ThunderPhone-Signature yalnızca ham gövdeyi imzalar. Mevcut doğrulayıcıların çalışmaya devam etmesi için değişmeden gönderilmeye devam eder.

Adımlar#

1. Ayrıştırmadan önce üst bilgiyi, yöntemi, ham yolu ve sorguyu ve ham gövdeyi okuyun.
2. Sırrınızı kullanarak <t>\n<METHOD>\n<path and query>\n<body> öğesinin onaltılık HMAC-SHA256 değerini hesaplayın.
3. t 300 saniyeden fazla sapmışsa veya sonuç sabit zamanlı bir karşılaştırmada v1 ile eşleşmiyorsa isteği reddedin.

Gövde, kanonik JSON serileştirmesidir (anahtarlar sıralı, ayırıcılar sıkıştırılmıştır) ve ilettiğimiz baytları tam olarak imzalarız. Doğrulama kılavuzu, imzalanan tam dizeyi, uygulamalı bir örneği, SDK olmadan kodu ve eski üst bilgiyi içerir.

from flask import Flask, abort, request
from thunderphone import verify_signature
 
app = Flask(__name__)
 
@app.post("/thunderphone-webhook")
def handle():
    query = request.query_string.decode()
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=WEBHOOK_SECRET,
        method=request.method,
        path=request.path + (f"?{query}" if query else ""),
        body=request.get_data(),  # raw bytes
    ):
        abort(401)
    event = request.get_json()
    # dispatch on event["type"] …
    return "", 204

import express from "express";
import { verifySignature } from "@thunderphone/sdk";
 
const app = express();
app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ok = verifySignature({
      header: req.header("X-ThunderPhone-Signature-V2"),
      secret: process.env.WEBHOOK_SECRET,
      method: req.method,
      path: req.originalUrl,
      body: req.body,
    });
    if (!ok) return res.sendStatus(401);
    const event = JSON.parse(req.body.toString("utf8"));
    // dispatch on event.type …
    res.sendStatus(204);
  },
);

Teslim semantiği#

Bu anlamlar uç nokta teslimatları için geçerlidir. Eski tek URL'li webhook, telefon görüşmesi telephony.incoming yapılandırma alışverişi hariç, yeniden denemesi olmayan tek bir eşzamanlı denemedir; bu alışveriş bir kez yeniden denenir.

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

Yeni entegrasyonlar, olayları uç nokta tabanlı webhook'lar aracılığıyla tüketmelidir. Yalnızca çağrıları yanıtlanma anı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#