Skip to main content

Webhooks e endpoints internos

Além da API v1, o Rouxinol expõe alguns endpoints usados internamente pela plataforma para receber eventos de provedores externos (Twilio, Meta) ou para a comunicação entre o navegador e o Janus. Eles não fazem parte da API pública para integradores e não usam OAuth2 — cada um tem seu próprio mecanismo de autenticação (ou nenhum). Documentados aqui apenas para referência.

POST /api/twilio/voice/inbound​

Webhook chamado pela Twilio para chamadas de entrada (PSTN). Valida a assinatura X-Twilio-Signature da requisição contra o auth_token configurado. Rejeita com 401 se a assinatura for inválida ou o auth_token não estiver configurado. Retorna TwiML instruindo a Twilio a discar para o SIP do Janus.

POST /api/sip-trunk/voice/inbound​

Webhook genérico de chamada de entrada para troncos SIP que não são Twilio. Autenticado por um header X-Webhook-Secret, comparado com o secret configurado no servidor. Falha fechado: se o secret não estiver configurado, a requisição é rejeitada.

curl -X POST "$ROUXINOL_URL/api/sip-trunk/voice/inbound" \
  -H "X-Webhook-Secret: SEU_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+551130001000", "from": "+5511988887777" }'

POST /api/openai/realtime/agents/{agent}/session​

Endpoint interno usado pela ponte de voz (navegador/telefonia) para abrir uma sessão WebRTC Realtime da OpenAI para um agente: recebe uma oferta SDP e devolve a resposta SDP.

warning

Este endpoint não tem verificação de autenticação própria — depende de só ser chamado a partir de fluxos internos confiáveis. Não deve ser exposto publicamente sem uma camada adicional de proteção.

POST /api/openai/realtime/function-call​

Recebe chamadas de função (transfer_call) disparadas pelo modelo durante uma sessão Realtime da OpenAI. Autenticado por um header X-Webhook-Secret comparado ao secret configurado.

danger

Se o secret não estiver configurado no servidor, a verificação é pulada (falha aberto) — diferente do endpoint de tronco SIP. Configure sempre o secret em produção.

GET|POST /api/whatsapp/webhook/{connection}​

Webhook padrão da WhatsApp Cloud API (Meta) para uma conexão específica.

  • GET — handshake de verificação da assinatura do webhook: a Meta envia hub_verify_token, comparado com o token cadastrado na conexão; se válido, o hub_challenge é ecoado de volta.
  • POST — entrega dos eventos. Apenas eventos de chamada (calls) são processados; se a conexão tiver uma proxy_url configurada, o evento também é encaminhado para lá.

Simulando o handshake de verificação (use o webhook_verify_token cadastrado na conexão):

curl "$ROUXINOL_URL/api/whatsapp/webhook/8?hub.mode=subscribe&hub.verify_token=SEU_VERIFY_TOKEN&hub.challenge=12345"
warning

A entrega via POST não verifica a assinatura X-Hub-Signature-256 do payload contra o app_secret — trate esse endpoint como confiável apenas por estar atrás do token de verificação do handshake inicial.

POST /api/whatsapp/test-call/{connection} e /hangup​

Usados exclusivamente pela ação Testar Ligação do painel administrativo, para simular uma chamada de teste via Janus sem depender de uma chamada real do WhatsApp. Não são destinados a uso por integrações externas.