Descripción general de los webhooks

Cómo ThunderPhone entrega eventos en tiempo real, cómo verificar firmas y cómo se comparan los modelos de entrega heredado y basado en endpoints.

ThunderPhone envía solicitudes HTTP POST a tu servidor cuando ocurren eventos durante una llamada: inicia una llamada entrante, termina una llamada, finaliza una ejecución de evaluación, se activa una alerta, entre otros. Hay dos modelos de entrega:

Todos los tipos de eventos enumerados en el catálogo de eventos se entregan mediante endpoints de webhook. Los seis eventos del ciclo de vida de las llamadas (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) también se envían al webhook heredado de una sola URL; si tienes tanto una URL heredada como un endpoint coincidente, recibes el evento en ambas rutas. El comportamiento bloqueante (el intercambio de configuración de telephony.incoming / web.incoming y el despacho de herramientas en modo webhook) existe exclusivamente en la ruta heredada; cada entrega a un endpoint es una notificación sin esperar respuesta.

Formato de la carga útil#

Las entregas a endpoints son un objeto JSON con data, event_id y type:

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

event_id es único para cada evento emitido. Es idéntico en todos los reintentos y en cada endpoint que recibe el evento; úsalo para deduplicar.

El webhook heredado de una sola URL envía el mismo type y data, pero sin event_id:

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

En la transmisión, cada cuerpo se serializa de forma canónica: claves ordenadas alfabéticamente, sin espacios en blanco, UTF-8. Los ejemplos con formato legible de esta documentación son solo para facilitar la lectura.

Consulta el catálogo de eventos para ver la lista completa de tipos de eventos y campos de carga útil.

Verificación de firma#

Cada solicitud incluye dos firmas, ambas HMAC-SHA256 con la secret del endpoint como clave (o la secret de webhook de tu organización para entregas heredadas):

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> firma la marca de tiempo, el método, la ruta y consulta, y el cuerpo sin procesar. Verifica esta firma y rechaza las solicitudes cuyo t difiera en más de 5 minutos de tu reloj para evitar que una solicitud capturada pueda reproducirse más tarde. Los reintentos se firman nuevamente cuando se envían.
• X-ThunderPhone-Signature firma únicamente el cuerpo sin procesar. Se sigue enviando, sin cambios, para que los verificadores existentes sigan funcionando.

Pasos#

1. Lee el encabezado, el método, la ruta y la consulta sin procesar, y el cuerpo sin procesar antes de realizar cualquier análisis.
2. Calcula el HMAC-SHA256 hexadecimal de <t>\n<METHOD>\n<path and query>\n<body> con tu secreto.
3. Rechaza la solicitud si t difiere en más de 300 segundos o si el resultado no coincide con v1 en una comparación de tiempo constante.

Los cuerpos son la serialización JSON canónica (claves ordenadas, separadores compactos), y firmamos exactamente los bytes que transmitimos. La guía de verificación incluye la cadena firmada exacta, un ejemplo práctico, código sin el SDK y el encabezado heredado.

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

Semántica de entrega#

Estas semánticas se aplican a las entregas de puntos de conexión. El webhook heredado de una sola URL realiza un único intento síncrono sin reintentos, excepto el intercambio de configuración de llamada telefónica telephony.incoming, que se reintenta una vez.

Elegir entre webhooks heredados y basados en endpoints#

Las nuevas integraciones deben consumir eventos mediante webhooks basados en endpoints. Conserva (o agrega) una URL heredada solo si configuras las llamadas dinámicamente al momento de atenderlas o usas el despacho de herramientas en modo webhook: esos intercambios de solicitud/respuesta solo se ejecutan en la ruta heredada.

Relacionado#