​

Configurar webhooks

​

Endpoints

​

Escopo por número

• 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"] }'

curl -X PATCH "https://pilotstatus.com.br/v1/webhooks/wh_abc" \
  -H "x-api-key: ps_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

curl -X DELETE "https://pilotstatus.com.br/v1/webhooks/wh_abc" \
  -H "x-api-key: ps_your_token_here"

curl "https://pilotstatus.com.br/v1/webhooks/wh_abc/logs?limit=20&event=message.received" \
  -H "x-api-key: ps_your_token_here"

​

Controle de 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

​

Verifique a assinatura

const crypto = require("node:crypto");
const expected = crypto.createHmac("sha256", process.env.WEBHOOK_SECRET).update(rawBody).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-pilot-status-signature"] ?? ""));

​

Painel