Vue d’ensemble des webhooks

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

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

Tous les types d'événements répertoriés dans le catalogue des événements sont transmis 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 hérité à URL unique. Si vous disposez à la fois d'une URL héritée 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 le répartiteur d'outils en mode webhook) se trouve exclusivement sur le chemin hérité ; chaque livraison vers un point de terminaison est une notification envoyée sans attente de réponse.

Format de la charge utile#

Les livraisons vers les 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 tentatives et pour chaque point de terminaison qui reçoit l'événement : dédupliquez sur cette valeur.

Le webhook hérité à 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, en UTF-8. Les exemples mis en forme dans cette documentation sont fournis uniquement pour 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 contient deux signatures, toutes deux HMAC-SHA256 utilisant le secret du point de terminaison comme clé (ou le secret webhook au niveau de votre organisation pour les livraisons héritées) :

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> signe l’ horodatage, la méthode, le chemin et la requête, ainsi que le corps brut. Vérifiez celle-ci et rejetez les requêtes dont t diffère de plus de 5 minutes de votre horloge afin qu’une requête interceptée ne puisse pas être rejouée ultérieurement. Les tentatives sont signées à nouveau lors de leur envoi.
• X-ThunderPhone-Signature signe uniquement le corps brut. Elle est toujours envoyée, sans modification, afin que les vérificateurs existants continuent de fonctionner.

Étapes#

1. Lisez l’en-tête, la méthode, le chemin et la requête bruts, ainsi que le corps brut avant toute analyse.
2. Calculez le HMAC-SHA256 hexadécimal de <t>\n<METHOD>\n<path and query>\n<body> avec votre secret.
3. Rejetez la requête si t diffère de plus de 300 secondes, ou si le résultat ne correspond pas à v1 lors d’une comparaison en temps constant.

Les corps utilisent la sérialisation JSON canonique (clés triées, séparateurs compacts), et nous signons exactement les octets que nous transmettons. Le guide de vérification contient la chaîne signée exacte, un exemple détaillé, du code sans le SDK et l’en-tête historique.

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

Sémantique de livraison#

Ces sémantiques s’appliquent aux livraisons de points de terminaison. Le webhook hérité à URL unique effectue une seule tentative synchrone sans nouvelle tentative, à l’exception de l’échange de configuration d’appel téléphonique telephony.incoming, qui fait l’objet d’une nouvelle tentative.

Choisir entre les webhooks historiques et ceux 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 fonctionnent que sur le chemin historique.

Associé#