Webhook apžvalga

Kaip ThunderPhone pateikia įvykius realiuoju laiku, kaip patikrinti parašus ir kuo skiriasi senasis bei galinio taško pagrindu veikiantys pateikimo 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 vertinimo vykdymas, suveikia įspėjimas ir pan. Yra du pristatymo modeliai:

Visi dešimt įvykių tipų, pateiktų įvykių kataloge, pristatomi per žiniatinklio kabliuko 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 į senąjį vienos URL žiniatinklio kabliuką — jei turite ir senąją URL, ir atitinkamą galinį tašką, įvykį gaunate abiejais keliais. Blokavimo veikimas ( telephony.incoming / web.incoming konfigūracijos mainai ir žiniatinklio kabliuko režimo įrankių iškvietimas) galimas tik senuoju keliu; kiekvienas pristatymas į galinį tašką yra pranešimas, kuriam atsakymo nelaukiama.

Naudingosios apkrovos formatas#

Į galinius taškus pristatoma 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 sugeneruotam įvykiui. Jis yra toks pats per pakartotinius bandymus ir visuose galiniuose taškuose, kurie gauna įvykį — naudokite jį dublikatams pašalinti.

Senasis vienos URL žiniatinklio kabliukas siunčia tuos 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 užklausos turinys serializuojamas kanoniškai — raktai surūšiuojami abėcėlės tvarka, nėra tarpų, naudojamas UTF-8. Šiuose dokumentuose pateikti skaitymui suformatuoti pavyzdžiai skirti tik aiškumui.

Visą įvykių tipų ir naudingosios apkrovos laukų sąrašą rasite įvykių kataloge.

Parašo patvirtinimas#

Kiekvienoje užklausoje antraštėje X-ThunderPhone-Signature pateikiamas HMAC-SHA256 parašas, apskaičiuotas pagal neapdorotą užklausos turinį. Pasirašymo raktas yra galinio taško secret (arba organizacijos lygio webhook secret, skirtas senesniems pristatymams).

Veiksmai#

1. Perskaitykite neapdorotą užklausos turinį prieš bet kokį analizavimą.
2. Apskaičiuokite hmac_sha256(secret, body).hexdigest().
3. Pastoviuoju laiku palyginkite su antrašte X-ThunderPhone-Signature.

Pasirašome tiksliai tuos baitus, kuriuos perduodame, o tie baitai yra kanoninis JSON serializavimas (surikiuoti raktai, kompaktiški skirtukai). Todėl patvirtinimas pagal neapdorotą turinį visada veikia — o jei jūsų sistema pateikia tik išanalizuotą JSON, pakartotinis jo serializavimas su surikiuotais raktais ir kompaktiškais skirtukais sukuria identiškus baitus. Abu būdai aprašyti patvirtinimo vadove.

import hmac
import hashlib
 
def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature or "")
 
# Example Flask handler
from flask import Flask, request, abort
app = Flask(__name__)
 
@app.post("/thunderphone-webhook")
def handle():
    body = request.get_data()
    sig = request.headers.get("X-ThunderPhone-Signature", "")
    if not verify_signature(body, sig, WEBHOOK_SECRET):
        abort(401)
    event = request.get_json()
    # dispatch on event["type"] …
    return "", 204

import crypto from "node:crypto";
import express from "express";
 
function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  if (!signature || expected.length !== signature.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}
 
const app = express();
app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.header("X-ThunderPhone-Signature") || "";
    if (!verifySignature(req.body, sig, process.env.WEBHOOK_SECRET)) {
      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 punkto pristatymams. Senasis vieno URL žiniatinklio kabliukas yra vienas sinchroninis bandymas be pakartotinių bandymų.

Pasirinkimas tarp senųjų ir galinių punktų pagrindu veikiančių žiniatinklio kabliukų#

Naujose integracijose įvykius reikėtų vartoti per galinių punktų pagrindu veikiančius žiniatinklio kabliukus. Senąjį URL palikite (arba pridėkite) tik jei dinamiškai konfigūruojate skambučius jų priėmimo metu arba naudojate žiniatinklio kabliuko režimo įrankių iškvietimą — šie užklausos ir atsakymo apsikeitimai vykdomi tik senuoju keliu.

Susiję#