Muhtasari wa Webhook

Jinsi ThunderPhone inavyowasilisha matukio ya wakati halisi, jinsi ya kuthibitisha sahihi, na jinsi miundo ya urithishaji na ya uwasilishaji inayotegemea endpoint inavyolinganishwa.

ThunderPhone hutuma maombi ya HTTP POST kwenye seva yako matukio yanapotokea wakati wa simu — simu inayoingia inaanza, simu inaisha, utekelezaji wa ukadiriaji unakamilika, arifa inawashwa, na kadhalika. Kuna miundo miwili ya uwasilishaji:

Aina zote za matukio zilizoorodheshwa katika katalogi ya matukio huwasilishwa kupitia vituo vya webhook. Matukio sita ya mzunguko wa simu (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) pia hutumwa kwenye webhook ya urithi ya URL moja — ikiwa una URL ya urithi na kituo kinacholingana, unapokea tukio kwenye njia zote mbili. Tabia ya kuzuia ( ubadilishanaji wa usanidi wa telephony.incoming / web.incoming na usambazaji wa zana wa hali ya webhook) ipo kwenye njia ya urithi pekee; kila uwasilishaji wa kituo ni arifa inayotumwa bila kusubiri jibu.

Muundo wa payload#

Uwasilishaji wa kituo ni objekti ya JSON yenye data, event_id, na type:

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

event_id ni ya kipekee kwa kila tukio linalotolewa. Inafanana katika majaribio upya na katika kila kituo kinachopokea tukio — tumia hiyo kuondoa nakala.

Webhook ya urithi ya URL moja hutuma type na data zilezile lakini bila event_id:

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

Kwenye mtandao, kila body husanifiwa kwa namna ya kanoni — funguo hupangwa kialfabeti, bila nafasi nyeupe, UTF-8. Mifano iliyopangwa kwa urahisi wa kusoma katika nyaraka hizi ni kwa ajili ya uelewekaji pekee.

Tazama Katalogi ya matukio kwa orodha kamili ya aina za matukio na sehemu za payload.

Uthibitishaji wa sahihi#

Kila ombi hubeba sahihi mbili, zote zikitumia ufunguo wa HMAC-SHA256 wenye secret ya endpoint (au secret ya webhook ya kiwango cha shirika lako kwa utumaji wa urithi):

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> husaini timestamp, mbinu, njia na query, pamoja na raw body. Thibitisha hii, na ukatae maombi ambayo t yake inatofautiana kwa zaidi ya dakika 5 na saa yako ili ombi lililonaswa lisichezeshwe tena baadaye. Jaribio la kutuma tena husainiwa upya linapotumwa.
• X-ThunderPhone-Signature husaini raw body pekee. Bado hutumwa bila kubadilishwa, ili vithibitishaji vilivyopo viendelee kufanya kazi.

Hatua#

1. Soma header, method, njia ghafi na query, na body ghafi kabla ya uchanganuzi wowote.
2. Kokotoa HMAC-SHA256 ya heksadesimali ya <t>\n<METHOD>\n<path and query>\n<body> kwa kutumia siri yako.
3. Kataa ombi ikiwa t imetofautiana kwa zaidi ya sekunde 300, au ikiwa matokeo hayalingani na v1 katika ulinganisho wa muda usiobadilika.

Miili ni uundaji wa mfululizo wa JSON wa kanoni (funguo zilizopangwa, vitenganishi vifupi), na tunatia sahihi byte halisi tunazotuma. mwongozo wa uthibitishaji una mfuatano kamili uliotiwa sahihi, mfano uliofafanuliwa, msimbo bila SDK, na header ya zamani.

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

Semantiki za uwasilishaji#

Semantiki hizi zinatumika kwa uwasilishaji wa endpoint. Webhook ya urithi ya URL moja ni jaribio moja la usawazishaji lisilo na majaribio ya kurudia, isipokuwa mabadilishano ya usanidi ya simu ya telephony.incoming, ambayo hujaribiwa tena mara moja.

Kuchagua kati ya webhook za zamani na webhook zinazotegemea endpoint#

Miunganisho mipya inapaswa kupokea matukio kupitia webhook zinazotegemea endpoint. Dumisha (au ongeza) URL ya zamani tu ikiwa unasanidi simu kwa kubadilika wakati wa kupokea simu au unatumia utumaji wa zana wa hali ya webhook — ubadilishanaji huo wa ombi/jibu huendeshwa kwenye njia ya zamani pekee.

Husika#