Webhook apžvalga

Kaip ThunderPhone perduoda įvykius realiuoju laiku, kaip patikrinti parašus ir kuo skiriasi senasis bei galinių taškų pagrindu veikiantys perdavimo modeliai.

ThunderPhone siunčia HTTP POST užklausas į jūsų serverį, kai skambučio metu įvyksta tam tikri veiksmai — prasideda įeinantis skambutis, baigiasi skambutis, užbaigiamas vertinimas, suveikia įspėjimas ir pan. Yra du pristatymo modeliai:

Visi įvykių kataloge išvardyti įvykių tipai pristatomi per žiniatinklio kabliukų galinius taškus. Šeši skambučio ciklo įvykiai (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) taip pat siunčiami į pasenusį vieno URL žiniatinklio kabliuką — jei turite ir pasenusį URL, ir atitinkamą galinį tašką, įvykį gaunate abiem keliais. Blokuojamasis veikimas (telephony.incoming / web.incoming konfigūracijos duomenų mainai ir žiniatinklio kabliuko režimo įrankių iškvietimas) galimas tik pasenusiu keliu; kiekvienas pristatymas į galinį tašką yra pranešimas be atsakymo laukimo.

Duomenų formato struktūra#

Pristatymai į galinius taškus yra JSON objektas su data, event_id ir type:

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

event_id yra unikalus kiekvienam išsiųstam įvykiui. Jis nesikeičia per pakartotinius bandymus ir visuose galiniuose taškuose, kurie gauna įvykį — naudokite jį dublikatams pašalinti.

Pasenęs vieno URL žiniatinklio kabliukas siunčia tokius pačius type ir data, tačiau be event_id:

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

Perduodant tinklu, kiekvienas turinys serializuojamas kanoniškai — raktai surikiuojami abėcėlės tvarka, nėra tarpų, naudojama UTF-8. Gražiai suformatuoti pavyzdžiai šioje dokumentacijoje pateikiami tik dėl skaitomumo.

Visą įvykių tipų ir duomenų laukų sąrašą rasite Įvykių kataloge.

Parašo tikrinimas#

Kiekviena užklausa turi du parašus, abu HMAC-SHA256 su galinio taško secret raktu (arba jūsų organizacijos lygio webhook secret, skirtu senesniems pristatymams):

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> pasirašo laiko žymą, metodą, kelią ir užklausos parametrus bei neapdorotą turinį. Patikrinkite šį parašą ir atmeskite užklausas, kurių t nuo jūsų laikrodžio skiriasi daugiau nei 5 minutes, kad perimtos užklausos vėliau nebūtų galima pakartoti. Pakartotiniai bandymai siunčiant pasirašomi iš naujo.
• X-ThunderPhone-Signature pasirašo tik neapdorotą turinį. Jis vis dar siunčiamas nepakitęs, kad esami tikrintuvai ir toliau veiktų.

Veiksmai#

1. Prieš bet kokį analizavimą nuskaitykite antraštę, metodą, neapdorotą kelią ir užklausą bei neapdorotą turinį.
2. Naudodami savo slaptą raktą apskaičiuokite <t>\n<METHOD>\n<path and query>\n<body> šešioliktainę HMAC-SHA256 reikšmę.
3. Atmeskite užklausą, jei t skiriasi daugiau nei 300 sekundžių arba jei rezultatas neatitinka v1 palyginant pastoviuoju laiku.

Turiniai yra kanoninė JSON serijinė forma (surikiuoti raktai, kompaktiški skirtukai), o mes pasirašome tiksliai tuos baitus, kuriuos perduodame. Patvirtinimo vadove pateikta tiksli pasirašyta eilutė, veikiantis pavyzdys, kodas be SDK ir senoji antraštė.

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

Pristatymo semantika#

Ši semantika taikoma galinio taško pristatymams. Senasis vieno URL webhook naudoja vieną sinchroninį bandymą be pakartotinių bandymų, išskyrus telefono skambučio telephony.incoming konfigūracijos apsikeitimą, kuris pakartojamas vieną kartą.

Pasirinkimas tarp senųjų ir galiniais taškais pagrįstų žiniatinklio pranešimų#

Naujos integracijos turėtų apdoroti įvykius per galiniais taškais pagrįstus žiniatinklio pranešimus. Palikite (arba pridėkite) senąjį URL tik jei skambučius konfigūruojate dinamiškai jų priėmimo metu arba naudojate žiniatinklio pranešimų režimo įrankių iškvietimą — šie užklausos ir atsakymo mainai vykdomi tik senuoju keliu.

Susiję#