Pular para o conteúdo principal

​
Configurar webhooks

Gerencie todo o ciclo de vida do webhook via API pública — ou use a página Webhooks do painel (/webhooks). Um webhook é configurado por número; uma vez configurado, os eventos são entregues automaticamente (não é necessário vincular chave de API).
Página de Webhooks do Pilot Status
Para payloads e a lista completa de eventos, consulte a referência de eventos.

​
Endpoints

MétodoEndpointDescrição
GET/v1/webhooksLista os webhooks visíveis no escopo da chave.
POST/v1/webhooksCria um webhook assinado em um número.
GET/v1/webhooks/{id}Busca um webhook.
PATCH/v1/webhooks/{id}Atualiza name, url, active, events.
DELETE/v1/webhooks/{id}Exclui permanentemente o webhook.
GET/v1/webhooks/{id}/logsTentativas de entrega recentes (limit 1–50, filtro event).

​
Escopo por número

Um webhook pertence a um único número do WhatsApp.
  • Com uma chave com escopo de número, o número vem da própria chave; um whatsappNumberId no corpo deve corresponder a ele (caso contrário, 400 NUMBER_MISMATCH).
  • Com uma chave com escopo de tenant, informe o número de destino pelo campo whatsappNumberId do corpo ou pelo cabeçalho x-whatsapp-number-id — omitir ambos retorna 400 NUMBER_REQUIRED; um número fora do seu tenant retorna 404 NUMBER_NOT_FOUND.
  • GET /v1/webhooks lista apenas os webhooks visíveis no escopo da chave (uma chave com escopo de número vê apenas os webhooks do seu próprio número). Um webhook fora do escopo da chave retorna 404 WEBHOOK_NOT_FOUND.

​
Exemplos

curl -X POST "https://pilotstatus.com.br/v1/webhooks" \
  -H "x-api-key: ps_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/in", "name": "My hook", "events": ["message.received", "message.sent"] }'

​
Controle de eventos

Uma lista events vazia (ou omitida) NÃO dispara NADA — não existe “assinar todos” implícito. Use "*" para assinar todos os eventos.
  • No PATCH, events substitui toda a lista de assinatura (não é uma mesclagem).
  • Eventos que o provedor do número não consegue emitir são descartados silenciosamente.

​
Regras e erros

RegraErro
Criar sem um número (chave com escopo de tenant, sem whatsappNumberId / cabeçalho)400 NUMBER_REQUIRED
whatsappNumberId difere do número de uma chave com escopo de número400 NUMBER_MISMATCH
whatsappNumberId no PATCH (o número não pode ser alterado após a criação — exclua e recrie)400 NUMBER_RESCOPE_NOT_SUPPORTED
Número fora do seu tenant404 NUMBER_NOT_FOUND
Webhook não visível no escopo da chave404 WEBHOOK_NOT_FOUND
O secret de assinatura nunca é retornado por nenhum desses endpoints.

​
Painel

Tudo acima também está disponível no painel em /webhooks: crie/edite webhooks por número, escolha eventos, pause/retome e inspecione os logs de entrega. A interface de Novo/Editar Webhook inclui o aviso de que message.read só dispara quando o destinatário tem os recibos de leitura do WhatsApp ativados.