Operations

Verifica le firme dei webhook

Ogni webhook e richiesta di strumenti inviata da ThunderPhone è firmata. Verifica la firma una volta con la procedura qui riportata, quindi riutilizza lo stesso controllo su ogni endpoint che esegui.

Ogni richiesta che inviamo al tuo server — consegne webhook e invocazioni di endpoint degli strumenti — include una firma HMAC-SHA256 nell'header X-ThunderPhone-Signature. Configura correttamente la verifica una volta e usa lo stesso helper in ogni handler.

L'algoritmo#

1. Leggi il corpo raw della richiesta — gli esatti byte che ti abbiamo inviato con POST.
2. Calcola hmac_sha256(secret, body).hexdigest().
3. Confronta in tempo costante con X-ThunderPhone-Signature. (Un semplice confronto di stringhe espone informazioni sui tempi.)

Firmiamo esattamente i byte che trasmettiamo, quindi la verifica del corpo raw funziona sempre. Quei byte corrispondono anche alla serializzazione JSON canonica del payload — chiavi ordinate alfabeticamente, separatori compatti (, e : senza spazi), UTF-8. Questo ti offre un secondo metodo del tutto equivalente quando il tuo framework espone solo JSON analizzato: serializzalo nuovamente in formato canonico e calcola l'HMAC su quello.

# Equivalent to hashing the raw body:
import json
canonical = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")

Preferisci il corpo raw — richiede un passaggio in meno ed evita le particolarità della conversione ripetuta dei numeri JSON in alcuni linguaggi.

Quale segreto?#

Archivia il segreto nel tuo gestore di segreti o in una variabile d'ambiente — non inserirlo mai nel repository.

Implementazioni di riferimento#

Tutte e quattro verificano il corpo raw della richiesta:

import hashlib
import hmac
 
 
def verify(body: bytes, signature: str, secret: str) -> bool:
    """Constant-time HMAC-SHA256 verification."""
    expected = hmac.new(
        secret.encode("utf-8"),
        body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature or "")

import crypto from "node:crypto";
 
export function verify(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),
  );
}

package webhook
 
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)
 
func Verify(body []byte, signature, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signature))
}

require "openssl"
 
def verify(body, signature, secret)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  Rack::Utils.secure_compare(expected, signature.to_s)
end

Configurazione specifica del framework#

from fastapi import FastAPI, HTTPException, Request
 
app = FastAPI()
 
@app.post("/thunderphone-webhook")
async def hook(request: Request):
    body = await request.body()           # raw bytes, NOT request.json()
    sig = request.headers.get("X-ThunderPhone-Signature", "")
    if not verify(body, sig, SECRET):
        raise HTTPException(status_code=401)
 
    import json
    event = json.loads(body)
    # … dispatch on event["type"] …
    return {"ok": True}

import express from "express";
 
const app = express();
 
app.post(
  "/thunderphone-webhook",
  // IMPORTANT: parse as raw; do NOT use express.json() here.
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.header("X-ThunderPhone-Signature") || "";
    if (!verify(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);
  },
);

import json
 
from django.http import JsonResponse, HttpResponseForbidden
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
 
 
@csrf_exempt
@require_POST
def hook(request):
    body = request.body  # raw bytes
    sig = request.headers.get("X-ThunderPhone-Signature", "")
    if not verify(body, sig, SECRET):
        return HttpResponseForbidden("invalid signature")
    event = json.loads(body)
    # … dispatch on event["type"] …
    return JsonResponse({"ok": True})

Verifica delle chiamate agli strumenti#

Quando l'agente richiama direttamente uno dei tuoi strumenti funzione (lo strumento dispone di un endpoint), la richiesta include due header ThunderPhone oltre ai tuoi endpoint.headers configurati:

• X-ThunderPhone-Call-ID — l'ID numerico della chiamata attiva.
• X-ThunderPhone-Signature — HMAC-SHA256, con chiave costituita dal tuo segreto webhook a livello di organizzazione, calcolato sui byte esatti del corpo della richiesta.

Lo stesso helper verify() funziona senza modifiche, con due particolarità:

1. Gli strumenti GET / DELETE non hanno un corpo. Gli argomenti vengono passati come parametri di query e la firma viene calcolata sulla stringa di byte vuota — quindi verify(b"", sig, secret) (Python) oppure verify(Buffer.alloc(0), sig, secret) (Node). Non calcolare l'hash della stringa di query.
2. Le organizzazioni senza un webhook legacy configurato non hanno un segreto dell'organizzazione. In questo caso le chiamate agli strumenti includono solo X-ThunderPhone-Call-ID e nessun header della firma. Configura il webhook legacy (PUT /v1/webhook) per ottenere un segreto di firma, oppure autentica le chiamate agli strumenti con un tuo header tramite endpoint.headers.

@app.post("/tools/search-appointments")
async def tool(request: Request):
    body = await request.body()  # b"" for GET/DELETE tools
    sig = request.headers.get("X-ThunderPhone-Signature", "")
    call_id = request.headers.get("X-ThunderPhone-Call-ID", "")
    if not verify(body, sig, ORG_WEBHOOK_SECRET):
        raise HTTPException(status_code=401)
    args = json.loads(body)
    ...

L'instradamento degli strumenti in modalità webhook (strumenti senza un endpoint, inviati al webhook della tua organizzazione come telephony.tool / web.tool) è un normale webhook firmato: si applica la procedura standard descritta sopra. Consulta Strumenti funzione per entrambe le forme di richiesta.

Errori comuni#

Passaggi successivi#