Webhook da API Perplexity Não Dispara: Passos para Corrigir

Você configurou um webhook na API Perplexity para receber dados em tempo real, mas o endpoint nunca recebe uma requisição POST. Isso geralmente acontece devido a uma configuração incorreta na URL do webhook, seleção errada de evento ou bloqueio de rede. Este artigo explica por que o webhook falha ao disparar e fornece correções passo a passo para fazê-lo funcionar.

Por que o Webhook da API Perplexity Não Dispara

A API Perplexity envia uma requisição POST para a URL do seu webhook quando um evento específico ocorre, como uma pesquisa concluída ou uma nova resposta. Se o webhook não disparar, uma de três coisas está errada. Primeiro, a URL fornecida está inacessível ou não retorna status 200 OK em até 5 segundos. Segundo, você assinou o evento errado ou nenhum evento. Terceiro, seu servidor ou firewall bloqueia a requisição de entrada dos servidores da Perplexity. A API também envia um ping de teste quando você salva o webhook pela primeira vez; se esse ping falhar, o webhook é desabilitado automaticamente.

Causas Raiz Comuns em Detalhe

A causa mais frequente é um certificado SSL inválido ou expirado no seu endpoint. A Perplexity exige HTTPS e valida a cadeia de certificados. Se o certificado for autoassinado ou expirado, a requisição é descartada. Outra causa comum é a ausência ou incorreção do nome do evento no payload de assinatura. A API aceita apenas nomes de eventos documentados na referência oficial, como search.completed ou answer.created. Um erro de digitação no nome do evento falha silenciosamente. Por fim, limitação de taxa ou lista de permissão de IP no seu lado pode rejeitar a requisição antes que sua aplicação a processe.

Passos para Corrigir um Webhook que Não Dispara

Siga estes passos em ordem. Após cada passo, teste o webhook disparando o evento manualmente ou usando a função de teste do painel da API.

Passo 1: Verificar a URL do Webhook e o Certificado SSL

1. Verifique o protocolo da URL
   A URL deve começar com https://. URLs HTTP são rejeitadas imediatamente. Exemplo: https://seudominio.com/webhook.
2. Teste o endpoint manualmente
   Use uma ferramenta como curl ou Postman para enviar uma requisição POST para a URL. O endpoint deve retornar HTTP 200 em até 5 segundos. Qualquer outro código de status ou tempo limite causa falha no webhook.
3. Valide o certificado SSL
   Abra a URL em um navegador e clique no ícone de cadeado. O certificado deve ser emitido por uma CA confiável e não estar expirado. Certificados autoassinados não são permitidos.

Passo 2: Confirmar a Assinatura do Evento

1. Faça login no painel da API Perplexity
   Acesse https://api.perplexity.ai/dashboard e navegue até Webhooks.
2. Inspecione os eventos assinados
   Clique na entrada do webhook. A lista de eventos assinados aparece. Certifique-se de que o evento esperado, como search.completed, esteja marcado.
3. Adicione eventos ausentes
   Se o evento estiver faltando, clique em Editar Webhook e marque o nome correto do evento no menu suspenso. Salve as alterações.

Passo 3: Verificar Regras de Rede e Firewall

1. Permita tráfego de entrada na porta 443
   O firewall do seu servidor deve aceitar conexões TCP na porta 443 de todos os IPs ou especificamente do intervalo de IP da Perplexity. Entre em contato com o suporte da Perplexity para obter a lista atual de IPs.
2. Desative a lista de permissão de IP temporariamente
   Se você tem uma lista de permissão de IP, remova-a e teste o webhook. Se o webhook disparar, adicione os IPs da Perplexity à lista de permissão.
3. Revise os logs do proxy reverso
   Se você usa Nginx ou Apache, verifique os logs de acesso para requisições de IPs da Perplexity. Uma entrada de log ausente significa que a requisição nunca chegou ao seu servidor.

Passo 4: Testar o Webhook Usando o Painel

1. Use o botão Enviar Teste
   Na página de edição do webhook, clique em Enviar Teste. A API envia um payload de teste para seu endpoint. Se o teste for bem-sucedido, o status do webhook muda para Ativo.
2. Verifique o log de resposta
   Após o teste, o painel mostra o código de status HTTP e o corpo da resposta do seu endpoint. Um status 200 confirma que o webhook está funcionando.
3. Dispare um evento real
   Realize uma ação que corresponda ao evento assinado, como executar uma consulta de pesquisa. O log do webhook deve mostrar uma nova entrada em segundos.

Se o Webhook Ainda Não Disparar

Se você completou todos os passos e o webhook permanece inativo, verifique estes padrões adicionais de falha.

Webhook Mostra Desabilitado Após Salvar

A API desabilita automaticamente um webhook se o ping de teste inicial falhar. Reative-o clicando em Habilitar no painel e corrija a URL ou o problema de SSL do Passo 1. O webhook será testado novamente.

Webhook Dispara Mas Payload Está Vazio

Um payload vazio geralmente significa que o evento ocorreu, mas nenhum dado correspondeu ao filtro de assinatura. Por exemplo, se você assina search.completed mas a pesquisa não retornou resultados, o payload pode conter apenas metadados. Verifique a documentação do evento para a estrutura esperada do payload.

Webhook Dispara Apenas Intermitentemente

Falhas intermitentes são frequentemente causadas por timeouts de rede ou limitação de taxa. Seu endpoint deve responder em até 5 segundos. Se sua aplicação processa a requisição lentamente, mova o processamento para um job em segundo plano e retorne 200 imediatamente. Verifique também se seu provedor de hospedagem bloqueia requisições repetidas do mesmo IP.

Eventos de Webhook da API Perplexity: Pesquisa Concluída vs Resposta Criada

Item	Pesquisa Concluída	Resposta Criada
Nome do evento	search.completed	answer.created
Condição de disparo	Perplexity conclui uma consulta de pesquisa	Perplexity gera uma resposta final a partir de fontes
Payload contém	Texto da consulta, número de fontes, duração	Texto da resposta, citações, pontuação de confiança
Caso de uso	Registro de atividade de pesquisa	Armazenamento ou encaminhamento da resposta

Agora você pode diagnosticar e corrigir um webhook da API Perplexity que falha ao disparar. Comece verificando a URL e o certificado SSL, depois confira a assinatura do evento e as regras de rede. Use a função de teste do painel para confirmar cada correção. Para confiabilidade avançada, configure um mecanismo de repetição no seu endpoint e monitore o log do webhook para entregas com falha.