Como Configurar Notificações Webhook da API Perplexity

Usuários da API Perplexity frequentemente precisam receber atualizações em tempo real quando uma busca ou análise é concluída, em vez de consultar a API manualmente. As notificações webhook permitem que o Perplexity envie os resultados diretamente para seu servidor quando uma tarefa termina, economizando largura de banda e reduzindo latência. Este artigo explica como configurar um endpoint webhook, registrá-lo no Perplexity e lidar com as notificações recebidas em seu backend. Você aprenderá as etapas exatas para habilitar a entrega de webhooks para sua chave de API.

Como Funcionam as Notificações Webhook do Perplexity

Um webhook é um callback HTTP que o Perplexity envia ao seu servidor quando um evento específico ocorre. Em vez de chamar repetidamente a API para verificar se uma busca foi concluída, o Perplexity envia o resultado para seu endpoint assim que é finalizado. Isso reduz o uso da API e fornece dados instantâneos.

Para usar webhooks, você precisa de um endpoint HTTPS publicamente acessível em seu servidor. O Perplexity envia uma requisição POST para esse endpoint com um corpo JSON. O payload inclui o ID da tarefa, o status (completed, failed ou cancelled) e os resultados da busca ou mensagem de erro. Você deve responder com um status 200 OK em até 5 segundos para confirmar o recebimento. Se o Perplexity não receber um 200, ele tenta novamente até três vezes com intervalos crescentes.

Cada requisição webhook inclui uma assinatura HMAC-SHA256 no cabeçalho X-Perplexity-Signature. Você deve verificar essa assinatura usando seu token secreto do webhook para garantir que a requisição realmente veio do Perplexity e não foi modificada durante o trânsito. Sem verificação, um invasor poderia enviar resultados falsos para seu servidor.

Passos para Registrar um Endpoint Webhook no Perplexity

1. Acesse o Painel do Perplexity
   Vá para perplexity.ai/settings/api. Faça login com suas credenciais. Você precisa ter uma assinatura de API ativa para acessar as configurações de webhook.
2. Abra a Página de Configuração de Webhooks
   Na barra lateral esquerda, clique em Webhooks. Esta página lista todos os endpoints webhook registrados para sua conta.
3. Clique em Adicionar Endpoint
   Clique no botão azul Adicionar Endpoint no canto superior direito. Um formulário é aberto com campos para URL do endpoint, token secreto e filtros de evento.
4. Insira a URL do Seu Endpoint
   Digite a URL HTTPS completa do endpoint do seu servidor que receberá os webhooks. Por exemplo: https://seudominio.com/perplexity-webhook. A URL deve usar HTTPS com um certificado SSL válido. O Perplexity não enviará requisições para URLs HTTP ou com certificados autoassinados.
5. Gere e Salve um Token Secreto
   No campo Token Secreto, digite uma string aleatória de pelo menos 32 caracteres. Você pode gerar uma usando um gerenciador de senhas ou um comando como openssl rand -hex 32. Copie este token e armazene-o com segurança em seu servidor. Você o usará para verificar as assinaturas dos webhooks recebidos.
6. Selecione os Eventos para Receber
   Marque as caixas dos eventos sobre os quais deseja ser notificado. Os eventos disponíveis são:
   – search.completed: Uma requisição de busca foi concluída com sucesso
   – search.failed: Uma requisição de busca retornou um erro
   – search.cancelled: Uma requisição de busca foi cancelada pelo usuário ou sistema
   Selecione pelo menos um evento. Para a maioria dos casos de uso, marque todos os três para se manter informado sobre cada mudança de estado.
7. Clique em Salvar Endpoint
   Clique no botão Salvar na parte inferior do formulário. O Perplexity envia uma notificação de teste para seu endpoint para verificar a conectividade. Seu servidor deve responder com um 200 OK em até 5 segundos. Se o teste falhar, o endpoint não é salvo e você verá uma mensagem de erro. Verifique os logs do servidor e o código do endpoint e tente novamente.

Como Lidar com Requisições Webhook Recebidas em Seu Servidor

Depois que seu endpoint estiver registrado, você deve escrever código no servidor para receber, verificar e processar as requisições POST recebidas. Abaixo está um fluxo de trabalho genérico que funciona em qualquer linguagem de programação. O exemplo usa Node.js com Express, mas a lógica se aplica a Python, Ruby, PHP ou qualquer outra linguagem.

Verificar a Assinatura HMAC-SHA256

Cada requisição webhook inclui um cabeçalho chamado X-Perplexity-Signature. O valor é uma string hexadecimal. Para verificá-lo, calcule um hash HMAC-SHA256 do corpo bruto da requisição usando seu token secreto como chave. Compare o hash calculado com o cabeçalho da assinatura. Se não corresponderem, rejeite a requisição com um status 401 Unauthorized e não processe o payload.

Analisar o Payload JSON

O corpo da requisição é um objeto JSON com a seguinte estrutura:

{
  "event": "search.completed",
  "task_id": "abc123-def456",
  "status": "completed",
  "result": {
    "query": "últimos artigos de pesquisa em IA",
    "answer": "...",
    "sources": ["..."],
    "created_at": "2025-03-15T10:30:00Z"
  },
  "error": null
}

O campo event informa qual evento acionou a notificação. O task_id corresponde ao ID que você recebeu ao enviar a requisição de busca. Use este ID para correlacionar o webhook com seus registros internos. O objeto result contém os resultados completos da busca se o evento for search.completed. Para search.failed, o campo error contém uma descrição da falha.

Responder com um 200 OK

Após verificar a assinatura e analisar o payload, envie uma resposta 200 OK com corpo vazio. O Perplexity espera essa resposta em até 5 segundos. Se você precisar realizar processamento pesado, faça-o de forma assíncrona após enviar o 200. Por exemplo, envie o payload para uma fila de mensagens ou um processador de tarefas em segundo plano.

Código de Exemplo em Node.js

const express = require('express');
const crypto = require('crypto');

const app = express();
const SECRET_TOKEN = 'seu-token-secreto-aqui';

app.post('/perplexity-webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-perplexity-signature'];
  const payload = req.body;
  const computed = crypto.createHmac('sha256', SECRET_TOKEN)
                         .update(payload)
                         .digest('hex');
  if (signature !== computed) {
    return res.status(401).send('Assinatura inválida');
  }
  const data = JSON.parse(payload);
  console.log('Webhook recebido:', data.event, data.task_id);
  // Processar o resultado de forma assíncrona
  res.status(200).send();
});

app.listen(3000, () => console.log('Listener de webhook na porta 3000'));

Erros Comuns na Configuração de Webhooks e Como Evitá-los

Teste de Webhook Falha com Erro 5xx

A causa mais comum é que o endpoint do seu servidor não está acessível pela internet. O Perplexity deve conseguir resolver seu domínio e estabelecer uma conexão TLS. Verifique se seu servidor está em execução, se seu firewall permite tráfego de entrada na porta 443 e se seu certificado SSL é válido e não autoassinado. Use uma ferramenta como curl para testar o endpoint manualmente: curl -X POST https://seudominio.com/perplexity-webhook -d '{"test": true}' -H "Content-Type: application/json".

Payload do Webhook Não é Processado

Se você perceber que o webhook chega nos logs do servidor, mas os dados não são salvos ou processados, o problema provavelmente está na lógica de processamento. Certifique-se de que está analisando o corpo JSON corretamente. Muitos frameworks analisam o corpo automaticamente, mas você deve usar o corpo bruto para verificar a assinatura. Se você analisar o corpo antes de verificar a assinatura, o hash não corresponderá. No Express, use express.raw() como mostrado acima e depois analise manualmente após a verificação.

Múltiplos Webhooks para a Mesma Tarefa

O Perplexity pode enviar webhooks duplicados se não receber um 200 OK em até 5 segundos. Se seu servidor responder lentamente, o mecanismo de repetição envia o mesmo payload novamente. Para lidar com duplicatas, torne seu processamento idempotente. Verifique se você já processou um task_id antes de salvar o resultado. Armazene IDs de tarefas processadas em um banco de dados ou cache com um TTL de pelo menos uma hora.

Item	Sem Webhooks	Com Webhooks
Método de consulta	Cliente chama GET /v1/search/status a cada poucos segundos	Perplexity envia POST para seu endpoint quando a tarefa termina
Volume de chamadas de API	Alto: muitas requisições de polling por tarefa	Baixo: um push por evento, sem polling
Latência do resultado	Até o intervalo de polling (ex.: 5 segundos de atraso)	Quase em tempo real (subsegundo)
Complexidade do servidor	Simples: apenas um endpoint GET	Moderada: deve verificar HMAC e lidar com repetições
Custo	Maior uso da API, mais largura de banda	Menor uso da API, menos largura de banda

Agora você pode configurar notificações webhook da API Perplexity para receber resultados de busca assim que forem concluídos. Comece registrando seu endpoint HTTPS no painel do Perplexity e gerando um token secreto. Em seguida, implemente a verificação de assinatura e o processamento idempotente em seu servidor. Para aplicações de alto tráfego, considere usar uma fila de mensagens como RabbitMQ ou Redis para desacoplar o recebimento do webhook do processamento pesado dos resultados. Isso garante que seu endpoint responda em até 5 segundos mesmo sob carga.