വെബ്ഹുക്കുകളുടെ അവലോകനം

കോൾ സമയത്ത് കാര്യങ്ങൾ സംഭവിക്കുമ്പോൾ — ഇൻബൗണ്ട് കോൾ ആരംഭിക്കുമ്പോൾ, കോൾ അവസാനിക്കുമ്പോൾ, ഗ്രേഡിംഗ് റൺ പൂർത്തിയാകുമ്പോൾ, അലേർട്ട് സജീവമാകുമ്പോൾ തുടങ്ങിയപ്പോൾ — 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 ഹെഡറിലെ raw request body-യുടെ HMAC-SHA256 സിഗ്നേച്ചറോടെയാണ് വരുന്നത്. സൈനിംഗ് കീ endpoint-ന്റെ secret ആണ് (അല്ലെങ്കിൽ പഴയ ഡെലിവറികൾക്കായി നിങ്ങളുടെ org-തല webhook secret).

ഘട്ടങ്ങൾ

1. ഏതെങ്കിലും parsing നടത്തുന്നതിന് മുമ്പ് raw request body വായിക്കുക.
2. hmac_sha256(secret, body).hexdigest() കണക്കാക്കുക.
3. X-ThunderPhone-Signature ഹെഡറുമായി constant time-ൽ താരതമ്യം ചെയ്യുക.

ഞങ്ങൾ അയയ്ക്കുന്ന ബൈറ്റുകൾ കൃത്യമായി അതേപടി സൈൻ ചെയ്യുന്നു. ആ ബൈറ്റുകൾ canonical JSON serialization ആണ് (sorted keys, compact separators). അതിനാൽ raw body ഉപയോഗിച്ചുള്ള പരിശോധന എപ്പോഴും പ്രവർത്തിക്കും — നിങ്ങളുടെ framework parsed JSON മാത്രം നൽകുന്നുവെങ്കിൽ, sorted keys-ഉം compact separators-ഉം ഉപയോഗിച്ച് അത് വീണ്ടും serialize ചെയ്യുന്നത് ഒരേ ബൈറ്റുകൾ സൃഷ്ടിക്കും. രണ്ട് രീതികളും പരിശോധനാ ഗൈഡിൽ ഉൾപ്പെടുത്തിയിട്ടുണ്ട്.

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

ഡെലിവറി സെമാന്റിക്സ്

ഈ സെമാന്റിക്സ് endpoint ഡെലിവറികൾക്ക് ബാധകമാണ്. ലെഗസി ഒറ്റ-URL webhook-ൽ റീട്രൈകളില്ലാത്ത ഒരൊറ്റ synchronous ശ്രമമാണുള്ളത്.

ലെഗസിയും endpoint-അടിസ്ഥാന webhook-കളും തമ്മിൽ തിരഞ്ഞെടുക്കൽ

പുതിയ ഇന്റഗ്രേഷനുകൾ endpoint-അടിസ്ഥാന webhook-കളിലൂടെ ഇവന്റുകൾ ഉപഭോഗം ചെയ്യണം. കോൾ എടുക്കുന്ന സമയത്ത് ഡൈനാമിക്കായി കോൾ കോൺഫിഗർ ചെയ്യുകയോ webhook-mode tool dispatch ഉപയോഗിക്കുകയോ ചെയ്യുന്നെങ്കിൽ മാത്രം ഒരു ലെഗസി URL നിലനിർത്തുക (അല്ലെങ്കിൽ ചേർക്കുക) — ആ request/response എക്സ്ചേഞ്ചുകൾ ലെഗസി പാതയിൽ മാത്രമേ പ്രവർത്തിക്കൂ.

ബന്ധപ്പെട്ടവ