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

కాల్ సమయంలో సంఘటనలు జరిగినప్పుడు — ఇన్‌బౌండ్ కాల్ ప్రారంభమైనప్పుడు, కాల్ ముగిసినప్పుడు, గ్రేడింగ్ రన్ పూర్తైనప్పుడు, అలర్ట్ ట్రిగ్గర్ అయినప్పుడు మొదలైనవి — 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ను ఉంచండి (లేదా జోడించండి) — ఆ అభ్యర్థన/ప్రతిస్పందన మార్పిడులు లెగసీ మార్గంలోనే నడుస్తాయి.

సంబంధితవి