Pregled spletnih kavljev

Kako ThunderPhone posreduje dogodke v realnem času, kako preverite podpise in kako se primerjata starejši model dostave ter model dostave, ki temelji na končnih točkah.

ThunderPhone pošlje zahteve HTTP POST na vaš strežnik, ko se med klicem nekaj zgodi — začne se dohodni klic, klic se konča, dokonča se ocenjevanje, sproži se opozorilo in podobno. Na voljo sta dva modela dostave:

Vse navedene vrste dogodkov v katalogu dogodkov so dostavljene prek končnih točk webhookov. Šest dogodkov življenjskega cikla klica (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) je prav tako poslanih v podedovani webhook z enim naslovom URL — če imate tako podedovani naslov URL kot ujemajočo se končno točko, dogodek prejmete po obeh poteh. Blokirajoče vedenje ( izmenjava konfiguracije telephony.incoming / web.incoming in pošiljanje orodij v načinu webhook) je na voljo izključno na podedovani poti; vsaka dostava na končno točko je obvestilo brez čakanja na odgovor.

Oblika koristnega tovora#

Dostave na končne točke so objekt JSON z data, event_id in type:

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

event_id je enoličen za vsak poslan dogodek. Enak je pri ponovnih poskusih in pri vsaki končni točki, ki prejme dogodek — na njegovi podlagi odstranjujte dvojnike.

Podedovani webhook z enim naslovom URL pošlje enaka type in data, vendar brez event_id:

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

Pri prenosu je vsako telo kanonično serializirano — ključi so razvrščeni po abecedi, brez presledkov, v UTF-8. Primeri z lepim oblikovanjem v tej dokumentaciji so namenjeni le boljši berljivosti.

Za celoten seznam vrst dogodkov in polj koristnega tovora si oglejte katalog dogodkov.

Preverjanje podpisa#

Vsaka zahteva vsebuje dva podpisa, oba HMAC-SHA256 s ključem secret končne točke (ali secret spletnega kavlja na ravni vaše organizacije za starejše dostave):

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> podpisuje časovni žig, metodo, pot in poizvedbo ter neobdelano telo. Preverite tega in zavrnite zahteve, pri katerih je t od vaše ure oddaljen več kot 5 minut, da prestrežene zahteve pozneje ni mogoče znova predvajati. Ponovni poskusi se ob pošiljanju znova podpišejo.
• X-ThunderPhone-Signature podpisuje samo neobdelano telo. Še vedno se pošilja nespremenjen, da obstoječi preverjevalniki še naprej delujejo.

Koraki#

1. Preberite glavo, metodo, neobdelano pot in poizvedbo ter neobdelano telo pred kakršnim koli razčlenjevanjem.
2. Izračunajte šestnajstiški HMAC-SHA256 za <t>\n<METHOD>\n<path and query>\n<body> s svojim skrivnim ključem.
3. Zahtevo zavrnite, če t odstopa za več kot 300 sekund ali če se rezultat pri primerjavi v konstantnem času ne ujema z v1.

Tela so kanonična serializacija JSON (razvrščeni ključi, strnjena ločila), mi pa podpišemo natanko bajte, ki jih posredujemo. Vodnik za preverjanje vsebuje natančen podpisani niz, izdelan primer, kodo brez SDK-ja in zastarelo glavo.

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);
  },
);

Semantika dostave#

Ta pravila veljajo za dostave na končne točke. Podedovani webhook z enim URL-jem izvede en sinhroni poskus brez ponovnih poskusov, razen izmenjave konfiguracije za telefonski klic telephony.incoming, ki se ponovi enkrat.

Izbira med podedovanimi webhooki in webhooki na podlagi končnih točk#

Nove integracije naj prejemajo dogodke prek webhookov na podlagi končnih točk. Podedovani URL obdržite (ali dodajte) le, če klice dinamično konfigurirate ob prevzemu ali uporabljate pošiljanje orodij v načinu webhook — te izmenjave zahtevkov in odgovorov se izvajajo samo na podedovani poti.

Povezano#