​

Configure webhooks

​

Endpoints

​

Number scoping

• With a number-scoped key the number comes from the key itself; a whatsappNumberId in the body must match it (else 400 NUMBER_MISMATCH).
• With a tenant-scoped key, pass the target number via the whatsappNumberId body field or the x-whatsapp-number-id header — omitting both returns 400 NUMBER_REQUIRED; a number outside your tenant returns 404 NUMBER_NOT_FOUND.
• GET /v1/webhooks lists only the webhooks visible to the key’s scope (a number-scoped key sees only its own number’s webhooks). A webhook outside the key’s scope returns 404 WEBHOOK_NOT_FOUND.

​

Examples

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"

​

Event gating

• On PATCH, events replaces the whole subscription list (it is not a merge).
• Events the number’s provider cannot emit are silently dropped.

​

Rules and errors

​

Verify the signature

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"] ?? ""));

​

Dashboard