વેબહુક્સનો પરિચય

ThunderPhone રીઅલ-ટાઇમ ઇવેન્ટ્સ કેવી રીતે પહોંચાડે છે, સહી કેવી રીતે ચકાસવી અને લેગસી તથા એન્ડપોઇન્ટ-આધારિત ડિલિવરી મોડલ્સની સરખામણી કેવી રીતે થાય છે.

ThunderPhone કૉલ દરમિયાન ઘટનાઓ બને ત્યારે તમારા સર્વર પર HTTP POST વિનંતીઓ મોકલે છે — ઇનબાઉન્ડ કૉલ શરૂ થાય, કૉલ સમાપ્ત થાય, ગ્રેડિંગ રન પૂર્ણ થાય, એલર્ટ ટ્રિગર થાય, વગેરે. બે ડિલિવરી મોડલ્સ છે:

ઇવેન્ટ્સ કેટલોગમાંના તમામ 10 ઇવેન્ટ પ્રકારો વેબહૂક એન્ડપૉઇન્ટ્સ દ્વારા ડિલિવર થાય છે. 6 કૉલ-લાઇફસાયકલ ઇવેન્ટ્સ (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 છે (અથવા લેગસી ડિલિવરી માટે તમારું org-સ્તરનું webhook 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 રાખો (અથવા ઉમેરો) — તે વિનંતી/પ્રતિસાદ વિનિમયો માત્ર લેગસી પાથ પર ચાલે છે.

સંબંધિત#