Registrar o webhook da Telnyx e solução de problemas de chamadas

Como registrar a Webhook URL do seu canal Telnyx no Mission Control e diagnosticar por que uma chamada não aparece na Caixa de entrada.

Jun 26, 2026

O que é isto e quando serve

O canal Telnyx (Voz programável) conecta seu número Telnyx ao Omnifox para fazer e receber chamadas dentro da Caixa de entrada. Para que cada evento da chamada (recebida, atendida, encerrada, gravação) apareça na conversa, a Telnyx precisa avisar o Omnifox por um webhook. Se o webhook não estiver registrado corretamente, as chamadas acontecem mas não aparecem no inbox — ou nem chegam até você.

Este guia é de nível intermediário: você já criou o canal e agora precisa registrar o webhook na Telnyx e diagnosticar por que uma chamada não chega.

Requisitos

  • Um canal Telnyx já criado em Canais → Conectar canal → Telnyx.
  • Acesso ao portal Telnyx Mission Control.
  • À mão: sua API Key, o Connection ID e, opcional mas recomendado, a Signing Key (chave pública Ed25519) da Connection.

Passos para registrar o webhook

  1. No Omnifox abra Canais, entre no seu canal Telnyx e copie o campo Webhook URL (somente leitura). Ele tem o formato https://omnifox.io/api/webhooks/telnyx.
  2. Na Telnyx vá em Voice API → Connections e abra a Connection usada para este número. O id dela é o Connection ID que você colou no Omnifox.
  3. Na aba Webhook da Connection, cole a Webhook URL do Omnifox em Webhook URL e escolha HTTP POST.
  4. Copie a Signing Key que a Telnyx mostra nessa mesma seção e cole no campo Public Key do canal no Omnifox. Com ela, o Omnifox verifica a assinatura Ed25519 de cada evento. Se deixar vazio, o Omnifox aceita os eventos sem verificar a assinatura (menos seguro).
  5. Confirme que o Connection ID e a API Key do canal no Omnifox coincidem com os do portal e salve.

Verificação

  • Faça uma chamada de teste real para o número. Na conversa do contato você deve ver, em ordem: Chamada recebida, Chamada atendida e Chamada encerrada com a duração.
  • Quando houver gravação, aparece a linha Gravação disponível com o link do MP3.
  • O Omnifox roteia cada evento procurando o Connection ID do payload; por isso o id do canal deve ser exatamente o da Connection que dispara a chamada.

Se não funcionar

  • Nenhum evento aparece: a Webhook URL não está colada na Connection certa, ou a Connection que recebe a chamada não é a do Connection ID configurado no Omnifox.
  • Chega um 403 / assinatura inválida: a Signing Key colada em Public Key não pertence a essa Connection. Copie de novo em Connection → Webhook → Signing Key, ou esvazie o campo temporariamente para confirmar que o resto do fluxo funciona.
  • "no channel route": o connection_id do evento não corresponde a nenhum canal. Verifique se o Connection ID no Omnifox está sem espaços.
  • Chamadas de saída falham: geralmente falta o número de origem (Default From). Configure-o no canal ou informe-o pela tela de chamada.

Dicas

  • Mantenha sempre a Signing Key configurada em produção: é a única forma de garantir que os eventos vêm mesmo da Telnyx.
  • Se você rotacionar a API Key na Telnyx, atualize-a também no Omnifox (veja o artigo de editar credenciais) ou as chamadas de saída deixarão de ser criadas.

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp