Webhooks கண்ணோட்டம்

ThunderPhone நிகழ்நேர நிகழ்வுகளை எவ்வாறு வழங்குகிறது, கையொப்பங்களை எவ்வாறு சரிபார்ப்பது, மற்றும் பழைய மற்றும் endpoint-அடிப்படையிலான விநியோக மாதிரிகள் எவ்வாறு ஒப்பிடப்படுகின்றன.

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 இல். இந்த ஆவணங்களில் உள்ள அழகாக வடிவமைக்கப்பட்ட எடுத்துக்காட்டுகள் வாசிப்பதற்கான வசதிக்காக மட்டுமே.

நிகழ்வு வகைகள் மற்றும் பேலோட் புலங்களின் முழுப் பட்டியலுக்கு நிகழ்வுகள் பட்டியலை பார்க்கவும்.

கையொப்பச் சரிபார்ப்பு#

ஒவ்வொரு கோரிக்கையிலும் இரண்டு கையொப்பங்கள் உள்ளன; இரண்டுமே endpoint-இன் secret-ஐப் பயன்படுத்தும் HMAC-SHA256 ஆகும் (அல்லது பழைய delivery-களுக்கான உங்கள் நிறுவன அளவிலான webhook secret):

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> என்பது timestamp, method, path மற்றும் query, மற்றும் raw body ஆகியவற்றில் கையொப்பமிடுகிறது. இதைச் சரிபார்த்து, உங்கள் கடிகார நேரத்திலிருந்து 5 நிமிடங்களுக்கு மேல் விலகிய t கொண்ட கோரிக்கைகளை நிராகரிக்கவும்; இதனால் கைப்பற்றப்பட்ட கோரிக்கையை பின்னர் மீண்டும் இயக்க முடியாது. மறுமுயற்சிகள் அனுப்பப்படும் போது மீண்டும் கையொப்பமிடப்படுகின்றன.
• X-ThunderPhone-Signature என்பது raw body-யில் மட்டும் கையொப்பமிடுகிறது. ஏற்கனவே உள்ள சரிபார்ப்பிகள் தொடர்ந்து செயல்படுவதற்காக, இது மாற்றமின்றி இன்னும் அனுப்பப்படுகிறது.

படிகள்#

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-ஐ வைத்திருக்கவும் (அல்லது சேர்க்கவும்) — அந்த கோரிக்கை/பதில் பரிமாற்றங்கள் மரபுப் பாதையில் மட்டுமே இயங்கும்.

தொடர்புடையவை#