Webhooks

Visão geral dos webhooks

Como o ThunderPhone entrega eventos em tempo real, como verificar assinaturas e como os modelos de entrega legado e baseado em endpoints se comparam.

O ThunderPhone envia solicitações HTTP POST ao seu servidor quando algo acontece durante uma chamada — uma chamada recebida começa, uma chamada termina, uma execução de avaliação é concluída, um alerta é disparado e assim por diante. Há dois modelos de entrega:

Todos os dez tipos de evento no catálogo de eventos são entregues por endpoints de webhook. Os seis eventos do ciclo de vida da chamada (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) também são enviados ao webhook legado de URL única — se você tiver uma URL legada e um endpoint correspondente, receberá o evento nos dois caminhos. O comportamento bloqueante (a troca de configuração de telephony.incoming / web.incoming e o despacho de ferramentas no modo webhook) existe exclusivamente no caminho legado; cada entrega ao endpoint é uma notificação sem aguardar resposta.

Formato do payload#

As entregas a endpoints são um objeto JSON com data, event_id e type:

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

event_id é exclusivo para cada evento emitido. Ele é idêntico entre novas tentativas e entre todos os endpoints que recebem o evento — faça a deduplicação por ele.

O webhook legado de URL única envia o mesmo type e data, mas sem event_id:

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

Na transmissão, cada corpo é serializado canonicamente — chaves ordenadas alfabeticamente, sem espaços em branco, UTF-8. Os exemplos formatados nestes documentos servem apenas para facilitar a leitura.

Consulte o Catálogo de eventos para ver a lista completa de tipos de evento e campos de payload.

Verificação de assinatura#

Cada solicitação contém uma assinatura HMAC-SHA256 sobre o corpo bruto da solicitação no cabeçalho X-ThunderPhone-Signature. A chave de assinatura é o secret do endpoint (ou o secret de webhook no nível da sua organização para entregas legadas).

Etapas#

1. Leia o corpo bruto da solicitação antes de qualquer análise.
2. Calcule hmac_sha256(secret, body).hexdigest().
3. Compare em tempo constante com o cabeçalho X-ThunderPhone-Signature.

Assinamos exatamente os bytes que transmitimos, e esses bytes são a serialização JSON canônica (chaves ordenadas, separadores compactos). Portanto, verificar em relação ao corpo bruto sempre funciona — e, se o seu framework fornecer apenas o JSON analisado, serializá-lo novamente com chaves ordenadas e separadores compactos produzirá bytes idênticos. Ambas as abordagens são abordadas no guia de verificação.

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

Semântica de entrega#

Estas semânticas se aplicam a entregas de endpoint. O webhook legado de URL única é uma única tentativa síncrona sem novas tentativas.

Escolha entre webhooks legados e baseados em endpoints#

Novas integrações devem consumir eventos por meio de webhooks baseados em endpoints. Mantenha (ou adicione) uma URL legada apenas se você configurar chamadas dinamicamente no momento do atendimento ou usar o despacho de ferramentas no modo webhook — essas trocas de solicitação/resposta são executadas apenas no caminho legado.

Relacionados#