Muhtasari wa Webhook

ThunderPhone hutuma maombi ya HTTP POST kwenye seva yako mambo yanapotokea wakati wa simu — simu inayoingia inaanza, simu inaisha, utekelezaji wa ukadiriaji 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 simu (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) pia hutumwa kwenye webhook ya urithi ya URL moja — ukiwa na 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 katika hali ya webhook) upo pekee kwenye njia ya urithi; kila uwasilishaji wa kituo ni arifa ya kutuma-bila-kusubiri.

Muundo wa payload

Uwasilishaji wa kituo ni kitu cha JSON chenye 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. Inabaki sawa katika majaribio 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" }
}

Kwenye mtandao, kila body huwekwa katika mpangilio wa kawaida — funguo hupangwa kialfabeti, bila nafasi nyeupe, UTF-8. Mifano yenye mpangilio wa kusomeka katika nyaraka hizi ni kwa urahisi wa kusoma pekee.

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

Uthibitishaji wa sahihi

Kila ombi hubeba sahihi ya HMAC-SHA256 juu ya mwili ghafi wa ombi katika kichwa cha X-ThunderPhone-Signature. Ufunguo wa kutia sahihi ni secret ya endpoint (au secret ya webhook ya kiwango cha org yako kwa utumaji wa urithi).

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 sahihi bayti kamili tunazotuma, na bayti hizo ni usawazishaji wa kawaida wa JSON (funguo zilizopangwa, vitenganishi vya mkato). Kwa hiyo kuthibitisha dhidi ya mwili ghafi hufanya kazi daima — na ikiwa framework yako inakupa JSON iliyochanganuliwa pekee, kuisawazisha tena kwa funguo zilizopangwa na vitenganishi vya mkato hutoa bayti zilezile. 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 usawazishaji lisilo na majaribio ya kurudia.

Kuchagua kati ya webhook za urithi na webhook 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 au unatumia utumaji wa zana wa hali ya webhook — ubadilishanaji huo wa ombi/jibu huendeshwa kwenye njia ya urithi pekee.

Yanayohusiana