Webhooks

Présentation des webhooks

Comment ThunderPhone transmet des événements en temps réel, comment vérifier les signatures et comment se comparent les modèles de transmission hérités et basés sur des endpoints.

ThunderPhone envoie des requêtes HTTP POST à votre serveur lorsque des événements se produisent pendant un appel — un appel entrant commence, un appel se termine, une exécution d'évaluation se termine, une alerte se déclenche, etc. Il existe deux modèles de livraison :

Les dix types d'événements du catalogue des événements sont livrés via des points de terminaison webhook. Les six événements du cycle de vie des appels (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) sont également envoyés au webhook historique à URL unique — si vous disposez à la fois d'une URL historique et d'un point de terminaison correspondant, vous recevez l'événement sur les deux chemins. Le comportement bloquant (l'échange de configuration telephony.incoming / web.incoming et la répartition des outils en mode webhook) existe exclusivement sur le chemin historique ; chaque livraison à un point de terminaison est une notification envoyée sans attente de réponse.

Format de la charge utile#

Les livraisons aux points de terminaison sont un objet JSON avec data, event_id et type :

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

event_id est unique pour chaque événement émis. Il est identique lors des nouvelles tentatives et sur chaque point de terminaison qui reçoit l'événement — dédupliquez à l'aide de cet identifiant.

Le webhook historique à URL unique envoie les mêmes type et data, mais sans event_id :

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

Sur le réseau, chaque corps est sérialisé de manière canonique — clés triées par ordre alphabétique, sans espaces, UTF-8. Les exemples mis en forme dans ces Docs sont uniquement destinés à faciliter la lecture.

Consultez le catalogue des événements pour obtenir la liste complète des types d'événements et des champs de charge utile.

Vérification de signature#

Chaque requête comporte une signature HMAC-SHA256 calculée sur le corps brut de la requête dans l’en-tête X-ThunderPhone-Signature. La clé de signature est le secret du point de terminaison (ou le secret de webhook au niveau de votre organisation pour les livraisons héritées).

Étapes#

1. Lisez le corps brut de la requête avant toute analyse.
2. Calculez hmac_sha256(secret, body).hexdigest().
3. Comparez-le en temps constant à l’en-tête X-ThunderPhone-Signature.

Nous signons exactement les octets que nous transmettons, et ces octets correspondent à la sérialisation JSON canonique (clés triées, séparateurs compacts). La vérification par rapport au corps brut fonctionne donc toujours — et si votre framework ne vous fournit que du JSON analysé, le re-sérialiser avec des clés triées et des séparateurs compacts produit des octets identiques. Les deux méthodes sont décrites dans le guide de vérification.

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

Sémantique de livraison#

Cette sémantique s'applique aux livraisons vers des points de terminaison. Le webhook historique à URL unique consiste en une seule tentative synchrone sans nouvelle tentative.

Choisir entre les webhooks historiques et basés sur des points de terminaison#

Les nouvelles intégrations doivent consommer les événements via des webhooks basés sur des points de terminaison. Conservez (ou ajoutez) une URL historique uniquement si vous configurez les appels dynamiquement au moment de la prise d'appel ou utilisez la répartition d'outils en mode webhook — ces échanges requête/réponse ne s'exécutent que sur le chemin historique.

Associé#