Visão geral dos webhooks

Como o ThunderPhone entrega eventos em tempo real, como verificar assinaturas e como os modelos de entrega legados e baseados em endpoint 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 tipos de evento listados no catálogo de eventos são entregues por meio de 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 em ambos os 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 a um endpoint é uma notificação enviada sem aguardar resposta.

Formato da carga útil#

As entregas aos 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 — use-o para eliminar duplicatas.

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 de forma canônica — chaves ordenadas alfabeticamente, sem espaços em branco, UTF-8. Os exemplos formatados nestas documentações são apenas para facilitar a leitura.

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

Verificação de assinatura#

Cada solicitação contém duas assinaturas, ambas HMAC-SHA256 com chave baseada no secret do endpoint (ou no secret de webhook no nível da sua organização para entregas legadas):

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> assina o carimbo de data e hora, o método, o caminho e a consulta, além do corpo bruto. Verifique esta assinatura e rejeite solicitações cujo t esteja a mais de 5 minutos do seu relógio para que uma solicitação capturada não possa ser reproduzida posteriormente. As tentativas são assinadas novamente quando são enviadas.
• X-ThunderPhone-Signature assina apenas o corpo bruto. Ela continua sendo enviada, sem alterações, para que os verificadores existentes continuem funcionando.

Etapas#

1. Leia o cabeçalho, o método, o caminho e a consulta brutos, e o corpo bruto antes de qualquer análise.
2. Calcule o HMAC-SHA256 em hexadecimal de <t>\n<METHOD>\n<path and query>\n<body> com seu segredo.
3. Rejeite a solicitação se t diferir em mais de 300 segundos ou se o resultado não corresponder a v1 em uma comparação de tempo constante.

Os corpos usam a serialização JSON canônica (chaves ordenadas, separadores compactos), e assinamos exatamente os bytes que transmitimos. O guia de verificação contém a string assinada exata, um exemplo completo, código sem o SDK e o cabeçalho legado.

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 aplicam a entregas de endpoint. O webhook legado de URL única é uma única tentativa síncrona, sem novas tentativas, exceto pela troca de configuração de chamada telefônica telephony.incoming, que é repetida uma vez.

Como escolher entre webhooks legados e baseados em endpoint#

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

Relacionados#