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.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 comdata, 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:
Verificação de assinatura
Cada solicitação inclui uma assinatura HMAC-SHA256 sobre o corpo bruto da solicitação no cabeçalhoX-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
- Leia o corpo bruto da solicitação antes de qualquer análise.
- Calcule
hmac_sha256(secret, body).hexdigest(). - Compare em tempo constante com o cabeçalho
X-ThunderPhone-Signature.
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.Novas tentativas
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.Ordenação
Ordenação
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.Duplicatas
Duplicatas
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.Tempos limite
Tempos limite
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.IPs de origem
IPs de origem
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.