Skip to main content
O ThunderPhone envia solicitações HTTP POST ao seu servidor quando eventos ocorrem 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:

Endpoints de webhook (recomendado)

Várias URLs, segredos por endpoint, filtros de eventos por endpoint e novas tentativas automáticas. Gerencie por meio de GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.

Webhook legado de URL única

Uma URL por organização. Transporta os eventos do ciclo de vida da chamada, incluindo os intercâmbios de configuração bloqueantes. Gerenciado em GET/PUT /v1/webhook.
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 em ambos os caminhos. O comportamento bloqueante (o intercâmbio 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 sem aguardar resposta.

Formato do payload

As entregas ao endpoint são um objeto JSON com data, event_id e type:
event_id é único para cada evento emitido. Ele é idêntico em novas tentativas e em 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:
Na transmissão, cada corpo é serializado de forma canônica — 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 inclui 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 correspondem à serialização JSON canônica (chaves ordenadas, separadores compactos). Portanto, a verificação com base no 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.

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.
Cada evento é tentado uma vez imediatamente. Qualquer resposta 2xx confirma a entrega. Em qualquer outro resultado (não-2xx, erro de conexão, tempo limite), fazemos novas tentativas após 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h da primeira tentativa — 8 tentativas ao longo de 24 horas. Se todas as tentativas falharem, a entrega é interrompida e o endpoint é marcado como status="failing" em endpoints de webhook. Retorne 2xx assim que o payload for aceito de forma durável; processe de maneira assíncrona.
A ordenação de entrega é feita conforme possível. Na prática, entregamos na ordem em que os eventos são emitidos, mas novas tentativas podem reordenar eventos em caso de falha. Sempre elimine duplicatas e reconcilie por call_id / id do objeto.
A entrega é pelo menos uma vez: uma nova tentativa após uma resposta que nunca recebemos pode duplicar um evento. Cada nova tentativa carrega o mesmo event_id, portanto armazene os ids processados e ignore repetições. event_id também é compartilhado entre endpoints — dois endpoints inscritos no mesmo evento recebem o mesmo event_id.
As entregas de endpoint têm um tempo limite de 30 s por tentativa. No caminho legado, as solicitações bloqueantes que orientam o comportamento de chamadas ao vivo — a troca de configuração telephony.incoming / web.incoming — expiram após 10 s, mas uma resposta lenta atrasa o atendimento da chamada, portanto busque responder em poucos segundos. A execução de ferramentas no modo webhook permite 20 s.
Webhooks de saída são originados da faixa de IPs de nuvem do ThunderPhone. Se seu firewall exigir uma lista de permissões, entre em contato com o suporte e compartilharemos as faixas atuais.

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 execução de ferramentas no modo webhook — essas trocas de solicitação/resposta são executadas apenas no caminho legado.

Relacionados

Catálogo de eventos

Todos os tipos de evento e seus payloads.

Endpoints de webhook

Gerencie vários endpoints, filtros de eventos e segredos.

telephony.incoming / web.incoming

A solicitação bloqueante à qual seu servidor deve responder para configurar chamadas.

telephony.complete / web.complete

Payload pós-chamada com transcrição, gravação e métricas.