Prehľad webhookov

Ako ThunderPhone doručuje udalosti v reálnom čase, ako overovať podpisy a ako sa porovnávajú starší model doručovania a model založený na koncových bodoch.

ThunderPhone odosiela požiadavky HTTP POST na váš server, keď počas hovoru dôjde k udalostiam — začne sa prichádzajúci hovor, hovor sa skončí, dokončí sa spustenie hodnotenia, aktivuje sa upozornenie a podobne. K dispozícii sú dva modely doručovania:

Všetky uvedené typy udalostí v katalógu udalostí sa doručujú prostredníctvom koncových bodov webhookov. Šesť udalostí životného cyklu hovoru (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) sa tiež odosiela do staršieho webhooku s jednou adresou URL — ak máte staršiu adresu URL aj zodpovedajúci koncový bod, udalosť prijmete na oboch cestách. Blokujúce správanie (výmena konfigurácie telephony.incoming / web.incoming a odosielanie nástrojov v režime webhooku) je dostupné výlučne cez staršiu cestu; každé doručenie na koncový bod je oznámenie typu fire-and-forget.

Formát údajov#

Doručenia na koncové body sú objektom JSON s položkami data, event_id a type:

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

event_id je jedinečné pre každú odoslanú udalosť. Je rovnaké pri opakovaných pokusoch aj na každom koncovom bode, ktorý udalosť prijme — odstraňujte duplicity podľa neho.

Starší webhook s jednou adresou URL odosiela rovnaké type a data, ale bez event_id:

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

Pri prenose je každé telo serializované kanonicky — kľúče sú zoradené abecedne, bez bielych znakov, v kódovaní UTF-8. Príklady s formátovaním v tejto dokumentácii slúžia len na lepšiu čitateľnosť.

Úplný zoznam typov udalostí a polí údajov nájdete v katalógu udalostí.

Overenie podpisu#

Každá požiadavka obsahuje dva podpisy, oba HMAC-SHA256 s kľúčom secret koncového bodu (alebo vaším secret webhooku na úrovni organizácie pre staršie doručenia):

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> podpisuje časovú pečiatku, metódu, cestu a dopyt aj nespracované telo. Overte tento podpis a odmietnite požiadavky, ktorých t sa od vášho času líši o viac než 5 minút, aby zachytenú požiadavku nebolo možné neskôr znovu prehrať. Opakované pokusy sa pri odoslaní podpisujú znova.
• X-ThunderPhone-Signature podpisuje iba nespracované telo. Stále sa odosiela nezmenený, aby existujúce overovače naďalej fungovali.

Kroky#

1. Prečítajte hlavičku, metódu, nespracovanú cestu a dopyt aj nespracované telo pred akýmkoľvek spracovaním.
2. Vypočítajte hexadecimálny HMAC-SHA256 hodnoty <t>\n<METHOD>\n<path and query>\n<body> pomocou svojho tajného kľúča.
3. Zamietnite požiadavku, ak sa t líši o viac než 300 sekúnd alebo ak sa výsledok nezhoduje s v1 pri porovnaní v konštantnom čase.

Telá sú kanonickou serializáciou JSON (zoradené kľúče, kompaktné oddeľovače) a podpisujeme presne tie bajty, ktoré prenášame. Sprievodca overením obsahuje presný podpisovaný reťazec, spracovaný príklad, kód bez SDK a staršiu hlavičku.

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

Sémantika doručovania#

Tieto sémantiky sa vzťahujú na doručenia do koncového bodu. Starší webhook s jednou URL je jeden synchrónny pokus bez opakovaní, okrem výmeny konfigurácie telefonátu telephony.incoming, ktorá sa opakuje raz.

Výber medzi staršími webhookmi a webhookmi založenými na koncových bodoch#

Nové integrácie by mali prijímať udalosti prostredníctvom webhookov založených na koncových bodoch. Staršiu adresu URL ponechajte (alebo pridajte) iba vtedy, ak konfigurujete hovory dynamicky pri ich prijatí alebo používate spúšťanie nástrojov v režime webhookov — tieto výmeny požiadaviek a odpovedí fungujú iba v staršej ceste.

Súvisiace#