Veebihaakide ülevaade

Kuidas ThunderPhone edastab reaalajas sündmusi, kuidas kontrollida allkirju ning kuidas võrrelda pärand- ja lõpp-punktipõhiseid edastusmudeleid.

ThunderPhone saadab sinu serverile HTTP POST päringuid, kui kõne ajal midagi toimub — sissetulev kõne algab, kõne lõpeb, hindamiskäitus lõpeb, hoiatus käivitub jne. Saadetiste jaoks on kaks mudelit:

Kõik sündmuste kataloogis loetletud sündmusetüübid edastatakse veebikonksu lõpp-punktide kaudu. Kuus kõne elutsükli sündmust (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) saadetakse samuti pärand-veebikonksule ühe URL-iga — kui sul on nii pärand-URL kui ka vastav lõpp-punkt, saad sündmuse kätte mõlemal teel. Blokeeriv käitumine (telephony.incoming / web.incoming seadistuste vahetus ja veebikonksurežiimi tööriista suunamine) on ainult pärandteel; iga lõpp-punkti edastus on vastust ootamata teavitus.

Andmevorming#

Lõpp-punkti edastused on JSON-objektid väljadega data, event_id ja type:

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

event_id on iga väljastatud sündmuse jaoks kordumatu. See on sama nii korduskatsete kui ka iga sündmust vastuvõtva lõpp-punkti puhul — kasuta seda duplikaatide eemaldamiseks.

Pärand-veebikonks ühe URL-iga saadab sama type ja data, kuid ilma event_id-ta:

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

Edastamisel serialiseeritakse iga sisu kanooniliselt — võtmed on tähestikulises järjekorras, tühikuid pole ja kasutatakse UTF-8 kodeeringut. Nendes dokumentides olevad vormindatud näited on ainult loetavuse jaoks.

Sündmusetüüpide ja andmeväljade täieliku loendi leiad sündmuste kataloogist.

Allkirja kontrollimine#

Igal päringul on kaks signatuuri, mõlemad HMAC-SHA256 algoritmiga, kasutades lõpp-punkti secret-it (või pärandkannete puhul sinu organisatsioonitaseme webhooki secret-it):

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> allkirjastab ajatempli, meetodi, tee ja päringu ning töötlemata sisu. Kontrolli seda ning lükka tagasi päringud, mille t erineb sinu kellaajast rohkem kui 5 minutit, et pealt võetud päringut ei saaks hiljem uuesti esitada. Uuesti proovimised allkirjastatakse saatmisel uuesti.
• X-ThunderPhone-Signature allkirjastab ainult töötlemata sisu. Seda saadetakse endiselt muutmata kujul, et olemasolevad kontrollijad töötaksid edasi.

Sammud#

1. Loe päis, meetod, toortee ja päring ning toorkeha enne mis tahes parsimist.
2. Arvuta oma saladusega stringi <t>\n<METHOD>\n<path and query>\n<body> heksadetsimaalne HMAC-SHA256.
3. Lükka päring tagasi, kui t erineb rohkem kui 300 sekundi võrra või kui tulemus ei ühti v1-ga konstantse ajaga võrdluses.

Päringukehad kasutavad kanonilist JSON-jadastust (sorditud võtmed, kompaktsed eraldajad) ning allkirjastame täpselt edastatavad baidid. Kontrollimise juhend sisaldab täpset allkirjastatud stringi, läbitöötatud näidet, SDK-ta koodi ja pärandpäist.

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

Edastamise semantika#

Need semantika kehtib lõpp-punkti edastuste kohta. Pärandne ühe URL-iga veebihaak on üks sünkroonne katse ilma korduskatseteta, välja arvatud telefonikõne telephony.incoming konfiguratsioonivahetus, mida proovime ühe korra uuesti.

Valimine pärand- ja lõpp-punktipõhiste veebikonksude vahel#

Uued integratsioonid peaksid tarbima sündmusi lõpp-punktipõhiste veebikonksude kaudu. Hoia (või lisa) pärand-URL ainult siis, kui seadistad kõnesid dünaamiliselt kõne vastuvõtmise ajal või kasutad veebikonksurežiimi tööriista väljakutsumist — need päringu/vastuse vahetused töötavad ainult pärandteel.

Seotud#