Webhookok áttekintése

Ismerje meg, hogyan továbbítja a ThunderPhone a valós idejű eseményeket, hogyan ellenőrizheti az aláírásokat, és hogyan viszonyul egymáshoz a régi és a végpontalapú kézbesítési modell.

ThunderPhone HTTP POST kéréseket küld az Ön szerverére, amikor egy hívás során események történnek — bejövő hívás indul, hívás ér véget, értékelési futás fejeződik be, riasztás aktiválódik stb. Két kézbesítési modell érhető el:

Az eseménykatalógusban felsorolt összes eseménytípus webhook-végpontokon keresztül kerül kézbesítésre. A hat hívás-életciklus esemény (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) szintén elküldésre kerül az örökölt, egy URL-es webhookhoz — ha örökölt URL-lel és megfelelő végponttal is rendelkezik, az eseményt mindkét útvonalon megkapja. A blokkoló viselkedés (a telephony.incoming / web.incoming konfigurációs adatcsere és a webhook módú eszközindítás) kizárólag az örökölt útvonalon érhető el; minden végpontkézbesítés indítás utáni értesítés.

Hasznos adat formátuma#

A végpontkézbesítések data, event_id és type mezőket tartalmazó JSON-objektumok:

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

Az event_id minden kibocsátott eseményhez egyedi. Újrapróbálkozások és az eseményt fogadó összes végpont esetén azonos — ez alapján végezzen deduplikációt.

Az örökölt, egy URL-es webhook ugyanazt a type és data mezőt küldi, de event_id nélkül:

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

A hálózaton minden törzs kanonikus formában szerializálódik — a kulcsok ábécérendben vannak, nincs szóköz, a kódolás UTF-8. A dokumentációban szereplő, formázott példák kizárólag az olvashatóságot szolgálják.

Az eseménytípusok és a hasznosadat-mezők teljes listáját az Eseménykatalógusban találja.

Aláírás-ellenőrzés#

Minden kérés két aláírást tartalmaz, mindkettő HMAC-SHA256, amelynek kulcsa a végpont secret értéke (vagy régebbi kézbesítések esetén a szervezetszintű webhook secret értéke):

• Az X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> aláírja az időbélyeget, a metódust, az útvonalat és a lekérdezést, valamint a nyers törzset. Ellenőrizze ezt, és utasítsa el azokat a kéréseket, amelyeknél a t értéke több mint 5 perccel eltér az Ön órájától, hogy egy elfogott kérést később ne lehessen újra lejátszani. Az újrapróbálkozásokat elküldéskor ismét aláírjuk.
• Az X-ThunderPhone-Signature csak a nyers törzset írja alá. Változatlanul továbbra is elküldjük, hogy a meglévő ellenőrzők továbbra is működjenek.

Lépések#

1. Olvassa be a fejlécet, a metódust, a nyers elérési utat és lekérdezést, valamint a nyers törzset bármilyen feldolgozás előtt.
2. Számítsa ki a <t>\n<METHOD>\n<path and query>\n<body> hexadecimális HMAC-SHA256 értékét a titkával.
3. Utasítsa el a kérést, ha a t több mint 300 másodperccel eltér, vagy ha az eredmény konstans idejű összehasonlításban nem egyezik a v1 értékkel.

A törzsek kanonikus JSON-szerializálásúak (rendezett kulcsokkal, tömör elválasztókkal), és pontosan az általunk továbbított bájtokat írjuk alá. Az ellenőrzési útmutató tartalmazza a pontos aláírt karakterláncot, egy kidolgozott példát, SDK nélküli kódot és az örökölt fejlécet.

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

Kézbesítési szemantika#

Ezek a szemantikák az endpoint kézbesítésekre vonatkoznak. A régi, egyetlen URL-t használó webhook egyetlen szinkron kísérletből áll, újrapróbálkozás nélkül, kivéve a telefonhívások telephony.incoming konfigurációs egyeztetését, amelyet egyszer újrapróbálunk.

Választás a régi és a végpont-alapú webhookok között#

Az új integrációknak végpont-alapú webhookokon keresztül kell eseményeket fogadniuk. Csak akkor tartson meg (vagy adjon hozzá) régi URL-t, ha a hívásokat dinamikusan konfigurálja felvételkor, vagy webhook módú eszközmeghívást használ — ezek a kérés/válasz cserék csak a régi útvonalon futnak.

Kapcsolódó#