Muhtasari wa Webhook

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

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

Aina zote kumi za matukio katika katalogi ya matukio huwasilishwa kupitia vituo vya webhook. Matukio sita ya mzunguko wa maisha 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 utumaji wa zana wa hali ya webhook) upo kwenye njia ya urithi pekee; kila uwasilishaji wa kituo ni arifa inayotumwa bila kusubiri jibu.

Muundo wa payload#

Uwasilishaji wa vituo 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 — ondoa nakala kwa kuitumia.

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" }
}

Katika usafirishaji wa mtandao, kila body husasishwa kwa mpangilio kanoniki — funguo hupangwa kialfabeti, bila nafasi nyeupe, UTF-8. Mifano iliyopangwa kwa urahisi wa kusoma katika nyaraka hizi ni kwa ajili ya usomaji pekee.

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

Uthibitishaji wa saini#

Kila ombi hubeba saini ya HMAC-SHA256 kwenye mwili ghafi wa ombi katika kichwa cha X-ThunderPhone-Signature. Ufunguo wa kutia saini ni secret ya endpoint (au secret ya webhook ya kiwango cha shirika lako kwa usafirishaji wa zamani).

Hatua#

1. Soma mwili ghafi wa ombi kabla ya uchanganuzi wowote.
2. Kokotoa hmac_sha256(secret, body).hexdigest().
3. Linganisha kwa muda usiobadilika na kichwa cha X-ThunderPhone-Signature.

Tunatia saini byte zilezile tunazotuma, na byte hizo ni uundaji wa JSON wa kanoni (funguo zilizopangwa, vitenganishi vifupi). Hivyo, uthibitishaji dhidi ya mwili ghafi hufanya kazi kila mara — na ikiwa fremu yako inakupa JSON iliyochanganuliwa pekee, kuiunda upya kwa funguo zilizopangwa na vitenganishi vifupi huzalisha byte zinazofanana. Mbinu zote mbili zimeelezwa katika mwongozo wa uthibitishaji.

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

Semantiki za uwasilishaji#

Semantiki hizi zinatumika kwa uwasilishaji wa endpoint. Webhook ya urithi ya URL moja ni jaribio moja la kisawazishaji lisilo na majaribio ya kurudia.

Kuchagua kati ya webhook za urithi na zinazotegemea endpoint#

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

Husika#