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

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 ആയി. ഈ ഡോക്യുമെന്റുകളിലെ വായിക്കാൻ എളുപ്പമായ ഫോർമാറ്റിലുള്ള ഉദാഹരണങ്ങൾ വായനാസൗകര്യത്തിനായി മാത്രമാണ്.

ഇവന്റ് തരങ്ങളുടെയും പേലോഡ് ഫീൽഡുകളുടെയും പൂർണ്ണ പട്ടികയ്ക്കായി ഇവന്റ്സ് കാറ്റലോഗ് കാണുക.

സിഗ്നേച്ചർ പരിശോധന#

ഓരോ അഭ്യർത്ഥനയിലും രണ്ട് ഒപ്പുകൾ ഉണ്ടായിരിക്കും; രണ്ടും എൻഡ്‌പോയിന്റിന്റെ secret ഉപയോഗിച്ച് കീ ചെയ്ത HMAC-SHA256 ആണ് (അല്ലെങ്കിൽ ലെഗസി ഡെലിവറികൾക്കായി നിങ്ങളുടെ ഓർഗ്-തല വെബ്‌ഹുക്കിന്റെ secret):

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> ടൈംസ്റ്റാമ്പ്, മെത്തഡ്, പാത്ത്, ക്വറി, റോ ബോഡി എന്നിവയിൽ ഒപ്പിടുന്നു. ഇത് പരിശോധിക്കുക; പിടിച്ചെടുത്ത ഒരു അഭ്യർത്ഥന പിന്നീട് വീണ്ടും പ്ലേ ചെയ്യുന്നത് തടയാൻ, നിങ്ങളുടെ ക്ലോക്കിൽ നിന്ന് t 5 മിനിറ്റിൽ കൂടുതലായി വ്യത്യാസപ്പെടുന്ന അഭ്യർത്ഥനകൾ നിരസിക്കുക. റീട്രൈകൾ അയയ്ക്കുമ്പോൾ അവയ്ക്ക് വീണ്ടും ഒപ്പിടും.
• X-ThunderPhone-Signature റോ ബോഡിയിൽ മാത്രം ഒപ്പിടുന്നു. നിലവിലുള്ള വെരിഫയറുകൾ പ്രവർത്തിച്ചുകൊണ്ടിരിക്കാനായി ഇത് മാറ്റമില്ലാതെ ഇപ്പോഴും അയയ്ക്കുന്നു.

ഘട്ടങ്ങൾ#

1. ഹെഡർ, മെത്തഡ്, റോ പാത്തും ക്വറിയും, റോ ബോഡിയും ഏതെങ്കിലും പാഴ്സിങ്ങിന് മുമ്പ് വായിക്കുക.
2. നിങ്ങളുടെ സീക്രട്ട് ഉപയോഗിച്ച് <t>\n<METHOD>\n<path and query>\n<body>-ന്റെ hex 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 webhook-ന് റീട്രൈകളില്ലാത്ത ഒറ്റ സിൻക്രണസ് ശ്രമമാണുള്ളത്; ഫോൺ കോൾ telephony.incoming കോൺഫിഗറേഷൻ എക്സ്ചേഞ്ച് ഒഴികെ, അതിന് ഒരു തവണ റീട്രൈ ഉണ്ടാകും.

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

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

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