Webhooks

Tīmekļa āķu pārskats

Kā ThunderPhone piegādā reāllaika notikumus, kā verificēt parakstus un kā salīdzināmi mantotais un galapunktos balstītais piegādes modelis.

ThunderPhone nosūta HTTP POST pieprasījumus uz jūsu serveri, kad zvana laikā notiek kāds notikums — sākas ienākošs zvans, zvans beidzas, tiek pabeigta novērtēšanas izpilde, tiek aktivizēts brīdinājums utt. Ir divi piegādes modeļi:

Visi desmit notikumu veidi notikumu katalogā tiek piegādāti, izmantojot tīmekļa aizķeru galapunktus. Seši zvana dzīves cikla notikumi (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) tiek arī nosūtīti uz mantoto tīmekļa aizķeri ar vienu URL — ja jums ir gan mantotais URL, gan atbilstošs galapunkts, notikumu saņemat pa abiem ceļiem. Bloķējošā darbība (telephony.incoming / web.incoming konfigurācijas apmaiņa un tīmekļa aizķera režīma rīku nosūtīšana) ir pieejama tikai mantotajā ceļā; katra piegāde uz galapunktu ir paziņojums bez atbildes gaidīšanas.

Lietderīgās slodzes formāts#

Galapunktu piegādes ir JSON objekts ar data, event_id un type:

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

event_id ir unikāls katram izsūtītajam notikumam. Tas ir identisks atkārtotos mēģinājumos un visos galapunktos, kas saņem notikumu — izmantojiet to dublikātu novēršanai.

Mantotais tīmekļa aizķeris ar vienu URL nosūta to pašu type un data, bet bez event_id:

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

Pārsūtē katrs pamatteksts tiek serializēts kanoniski — atslēgas sakārtotas alfabētiski, bez atstarpēm, UTF-8. Šajā dokumentācijā glīti formatētie piemēri ir paredzēti tikai lasāmībai.

Skatiet Notikumu katalogu, lai iegūtu pilnu notikumu veidu un lietderīgās slodzes lauku sarakstu.

Paraksta verifikācija#

Katram pieprasījumam galvenē X-ThunderPhone-Signature ir HMAC-SHA256 paraksts pār neapstrādāto pieprasījuma pamattekstu. Parakstīšanas atslēga ir galapunkta secret (vai jūsu organizācijas līmeņa tīmekļa aizķeres secret mantotajām piegādēm).

Darbības#

1. Nolasiet neapstrādāto pieprasījuma pamattekstu pirms jebkādas parsēšanas.
2. Aprēķiniet hmac_sha256(secret, body).hexdigest().
3. Salīdziniet to ar galveni X-ThunderPhone-Signature konstantā laikā.

Mēs parakstām tieši baitus, ko nosūtām, un šie baiti ir kanoniskā JSON serializācija (sakārtotas atslēgas, kompakti atdalītāji). Tāpēc verifikācija pret neapstrādāto pamattekstu vienmēr darbojas — un, ja jūsu ietvars nodod tikai parsētu JSON, tā atkārtota serializēšana ar sakārtotām atslēgām un kompaktiem atdalītājiem rada identiskus baitus. Abas metodes ir aprakstītas verifikācijas ceļvedī.

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

Piegādes semantika#

Šī semantika attiecas uz galapunktu piegādēm. Mantotais viena URL webhook ir viens sinhrons mēģinājums bez atkārtotiem mēģinājumiem.

Izvēle starp mantotajiem un uz galapunktiem balstītajiem webhookiem#

Jaunām integrācijām notikumi jāsaņem, izmantojot uz galapunktiem balstītus webhookus. Saglabājiet (vai pievienojiet) mantoto URL tikai tad, ja konfigurējat zvanus dinamiski zvana pieņemšanas laikā vai izmantojat webhook režīma rīku izsaukšanu — šīs pieprasījuma/atbildes apmaiņas darbojas tikai mantotajā ceļā.

Saistīts#