వెబ్‌హుక్స్ అవలోకనం

ThunderPhone రియల్-టైమ్ ఈవెంట్‌లను ఎలా అందిస్తుందో, సంతకాలను ఎలా ధృవీకరించాలో, అలాగే లెగసీ మరియు ఎండ్‌పాయింట్-ఆధారిత డెలివరీ మోడల్‌లను ఎలా పోల్చాలో తెలుసుకోండి.

ThunderPhone కాల్ సమయంలో సంఘటనలు జరిగినప్పుడు మీ సర్వర్‌కు HTTP POST అభ్యర్థనలను పంపుతుంది — ఇన్‌బౌండ్ కాల్ ప్రారంభమైనప్పుడు, కాల్ ముగిసినప్పుడు, గ్రేడింగ్ రన్ పూర్తైనప్పుడు, అలర్ట్ ట్రిగర్ అయినప్పుడు మొదలైనవి. రెండు డెలివరీ మోడళ్లు ఉన్నాయి:

ఈవెంట్‌ల కేటలాగ్లోని మొత్తం పది ఈవెంట్ రకాలు వెబ్‌హుక్ ఎండ్‌పాయింట్ల ద్వారా డెలివర్ చేయబడతాయి. ఆరు కాల్-లైఫ్‌సైకిల్ ఈవెంట్‌లు (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) లెగసీ ఒకే-URL వెబ్‌హుక్‌కు కూడా పంపబడతాయి — మీకు లెగసీ URL మరియు సరిపోలే ఎండ్‌పాయింట్ రెండూ ఉంటే, మీరు ఈవెంట్‌ను రెండు మార్గాల్లో స్వీకరిస్తారు. బ్లాకింగ్ ప్రవర్తన (telephony.incoming / web.incoming కాన్ఫిగరేషన్ ఎక్స్ఛేంజ్ మరియు వెబ్‌హుక్-మోడ్ టూల్ డిస్పాచ్) ప్రత్యేకంగా లెగసీ మార్గంలోనే ఉంటుంది; ప్రతి ఎండ్‌పాయింట్ డెలివరీ ప్రతిస్పందన కోసం వేచి ఉండని నోటిఫికేషన్.

పేలోడ్ ఫార్మాట్#

ఎండ్‌పాయింట్ డెలివరీలు data, event_id, మరియు typeతో కూడిన JSON ఆబ్జెక్ట్:

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

event_id విడుదల చేయబడిన ప్రతి ఈవెంట్‌కు ప్రత్యేకమైనది. ఇది రీట్రైల అంతటా మరియు ఈవెంట్‌ను స్వీకరించే ప్రతి ఎండ్‌పాయింట్‌లో ఒకేలా ఉంటుంది — దీని ఆధారంగా డూప్లికేట్‌లను తొలగించండి.

లెగసీ ఒకే-URL వెబ్‌హుక్ అదే type మరియు dataను పంపుతుంది, కానీ event_id లేకుండా:

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

ప్రసారంలో, ప్రతి బాడీ ప్రామాణికంగా సీరియలైజ్ చేయబడుతుంది — కీలు అక్షర క్రమంలో సార్ట్ చేయబడతాయి, వైట్‌స్పేస్ ఉండదు, UTF-8 ఉపయోగించబడుతుంది. ఈ డాక్యుమెంటేషన్‌లోని చదవడానికి సులభమైన ఉదాహరణలు స్పష్టత కోసం మాత్రమే.

ఈవెంట్ రకాలు మరియు పేలోడ్ ఫీల్డ్‌ల పూర్తి జాబితా కోసం ఈవెంట్‌ల కేటలాగ్ చూడండి.

సిగ్నేచర్ ధృవీకరణ#

ప్రతి రిక్వెస్ట్‌లో X-ThunderPhone-Signature హెడర్‌లో రా రిక్వెస్ట్ బాడీపై HMAC-SHA256 సిగ్నేచర్ ఉంటుంది. సైనింగ్ కీ అనేది ఎండ్‌పాయింట్‌కు చెందిన secret (లేదా లెగసీ డెలివరీల కోసం మీ సంస్థ-స్థాయి వెబ్‌హుక్ secret).

దశలు#

1. ఏదైనా పార్సింగ్‌కు ముందు రా రిక్వెస్ట్ బాడీని చదవండి.
2. hmac_sha256(secret, body).hexdigest()ను గణించండి.
3. X-ThunderPhone-Signature హెడర్‌తో స్థిర సమయ పద్ధతిలో పోల్చండి.

మేము పంపే బైట్‌లనే సరిగ్గా సైన్ చేస్తాము, ఆ బైట్‌లు కానానికల్ JSON సీరియలైజేషన్‌ (క్రమబద్ధమైన కీలు, కాంపాక్ట్ సెపరేటర్‌లు). కాబట్టి రా బాడీతో ధృవీకరించడం ఎల్లప్పుడూ పనిచేస్తుంది — మీ ఫ్రేమ్‌వర్క్ మీకు పార్స్ చేసిన JSONను మాత్రమే ఇస్తే, దానిని క్రమబద్ధమైన కీలు మరియు కాంపాక్ట్ సెపరేటర్‌లతో మళ్లీ సీరియలైజ్ చేయడం ఒకే విధమైన బైట్‌లను ఉత్పత్తి చేస్తుంది. రెండు పద్ధతులూ ధృవీకరణ గైడ్లో ఉన్నాయి.

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

డెలివరీ సెమాంటిక్స్#

ఈ సెమాంటిక్స్ ఎండ్‌పాయింట్ డెలివరీలకు వర్తిస్తాయి. లెగసీ సింగిల్-URL వెబ్‌హుక్‌లో రీట్రైలు లేకుండా ఒకే సింక్రోనస్ ప్రయత్నం ఉంటుంది.

లెగసీ మరియు ఎండ్‌పాయింట్ ఆధారిత వెబ్‌హుక్‌ల మధ్య ఎంచుకోవడం#

కొత్త ఇంటిగ్రేషన్‌లు ఎండ్‌పాయింట్ ఆధారిత వెబ్‌హుక్‌ల ద్వారా ఈవెంట్‌లను వినియోగించాలి. మీరు పికప్ సమయంలో కాల్‌లను డైనమిక్‌గా కాన్ఫిగర్ చేస్తే లేదా వెబ్‌హుక్-మోడ్ టూల్ డిస్పాచ్‌ను ఉపయోగిస్తే మాత్రమే లెగసీ URLను ఉంచండి (లేదా జోడించండి) — ఆ అభ్యర్థన/ప్రతిస్పందన మార్పిడులు లెగసీ మార్గంలో మాత్రమే నడుస్తాయి.

సంబంధిత#