વેબહુક્સનો અવલોકન

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

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

ઇવેન્ટ્સ કૅટલોગમાં સૂચિબદ્ધ તમામ ઇવેન્ટ પ્રકારો webhook એન્ડપોઇન્ટ્સ દ્વારા ડિલિવર થાય છે. છ કૉલ-લાઇફસાયકલ ઇવેન્ટ્સ (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) લેગસી સિંગલ-URL webhook પર પણ મોકલાય છે — જો તમારી પાસે લેગસી URL અને મેળ ખાતો એન્ડપોઇન્ટ બંને હોય, તો તમને ઇવેન્ટ બંને પાથ પર મળે છે. અવરોધક વર્તન (telephony.incoming / web.incoming કૉન્ફિગરેશન એક્સચેન્જ અને webhook-મોડ ટૂલ ડિસ્પૅચ) માત્ર લેગસી પાથ પર જ ઉપલબ્ધ છે; દરેક એન્ડપોઇન્ટ ડિલિવરી ફાયર-એન્ડ-ફૉર્ગેટ નોટિફિકેશન છે.

પેલોડ ફોર્મેટ#

એન્ડપોઇન્ટ ડિલિવરી 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 webhook એ જ type અને data મોકલે છે, પરંતુ event_id વિના:

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

વાયર પર, દરેક બોડી કેનોનિકલી સિરિયલાઇઝ થાય છે — કીઝ મૂળાક્ષર ક્રમમાં સૉર્ટ કરેલી, કોઈ વ્હાઇટસ્પેસ નહીં, UTF-8. આ દસ્તાવેજોમાં પ્રિટી-પ્રિન્ટ કરેલા ઉદાહરણો માત્ર વાંચવાની સુવિધા માટે છે.

ઇવેન્ટ પ્રકારો અને પેલોડ ફીલ્ડ્સની સંપૂર્ણ સૂચિ માટે ઇવેન્ટ્સ કૅટલોગ જુઓ.

સહી ચકાસણી#

દરેક વિનંતીમાં બે સહી હોય છે, જે બંને endpointના secret (અથવા legacy ડિલિવરી માટે તમારા org-સ્તરના webhook secret) વડે કી કરાયેલ HMAC-SHA256 છે:

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> timestamp, method, path અને query, તેમજ raw body પર સહી કરે છે. આની ચકાસણી કરો અને એવા વિનંતીઓ નકારી કાઢો જેમનું t તમારી ઘડિયાળ કરતાં 5 મિનિટથી વધુ દૂર હોય, જેથી કૅપ્ચર કરેલી વિનંતી પછીથી ફરી ચલાવી ન શકાય. ફરી પ્રયાસો મોકલાય ત્યારે તેમની પર ફરીથી સહી કરવામાં આવે છે.
• X-ThunderPhone-Signature માત્ર raw body પર સહી કરે છે. હાલના verifiers કાર્યરત રહે તે માટે તે હજી પણ અપરિવર્તિત રીતે મોકલવામાં આવે છે.

પગલાં#

1. કોઈપણ પાર્સિંગ પહેલાં હેડર, મેથડ, રૉ પાથ અને ક્વેરી, તથા રૉ બોડી વાંચો.
2. તમારા સિક્રેટ સાથે <t>\n<METHOD>\n<path and query>\n<body> નો હેક્સ HMAC-SHA256 ગણો.
3. જો t 300 સેકન્ડથી વધુ સમયથી અલગ હોય અથવા કોન્સ્ટન્ટ-ટાઇમ સરખામણીમાં પરિણામ v1 સાથે મેળ ખાતું ન હોય, તો રિક્વેસ્ટ નકારી કાઢો.

બોડીઝ કેનોનિકલ JSON સિરિયલાઇઝેશન છે (સૉર્ટ કરેલી કીઝ, કોમ્પેક્ટ સેપરેટર્સ), અને અમે મોકલીએ છીએ તે જ બાઇટ્સ પર સહી કરીએ છીએ. વેરિફિકેશન માર્ગદર્શિકામાં ચોક્કસ સહી કરેલી સ્ટ્રિંગ, એક કાર્યકારી ઉદાહરણ, SDK વગરનો કોડ અને લેગસી હેડર છે.

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

ડિલિવરી સીમેન્ટિક્સ#

આ અર્થઘટનો એન્ડપૉઇન્ટ ડિલિવરીઓ પર લાગુ પડે છે. લેગસી સિંગલ-URL વેબહૂક એક જ સમકાલીન પ્રયાસ છે જેમાં કોઈ પુનઃપ્રયાસ નથી, સિવાય કે ફોન-કૉલ telephony.incoming રૂપરેખાંકન વિનિમય, જેને એક વાર ફરી પ્રયાસ કરવામાં આવે છે.

લેગસી અને એન્ડપોઇન્ટ-આધારિત વેબહૂક્સ વચ્ચે પસંદગી#

નવી ઇન્ટિગ્રેશન્સે એન્ડપોઇન્ટ-આધારિત વેબહૂક્સ દ્વારા ઇવેન્ટ્સ વાપરવી જોઈએ. જો તમે પિકઅપ સમયે કૉલ્સને ડાયનેમિક રીતે કન્ફિગર કરો છો અથવા વેબહૂક-મોડ ટૂલ ડિસ્પેચ વાપરો છો, તો જ લેગસી URL રાખો (અથવા ઉમેરો) — આ વિનંતી/પ્રતિસાદ વિનિમયો માત્ર લેગસી પાથ પર ચાલે છે.

સંબંધિત#