Skip to main content

​
Configure webhooks

Manage the full webhook lifecycle via the public API — or use the dashboard Webhooks page (/webhooks). A webhook is configured per number; once configured, events are delivered automatically (no API-key linking is required). For payloads and the full event list, see the event reference.

​
Endpoints

MethodEndpointDescription
GET/v1/webhooksList the webhooks visible to the key’s scope.
POST/v1/webhooksCreate a webhook subscribed to one number.
GET/v1/webhooks/{id}Fetch one webhook.
PATCH/v1/webhooks/{id}Update name, url, active, events.
DELETE/v1/webhooks/{id}Permanently delete the webhook.
GET/v1/webhooks/{id}/logsRecent delivery attempts (limit 1–50, event filter).

​
Number scoping

A webhook belongs to a single WhatsApp number.
  • 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"] }'

​
Event gating

An empty (or omitted) events list dispatches NOTHING — there is no implicit “subscribe to all”. Use "*" to subscribe to every event.
  • 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

RuleError
Create without a number (tenant-scoped key, no whatsappNumberId / header)400 NUMBER_REQUIRED
whatsappNumberId differs from a number-scoped key’s number400 NUMBER_MISMATCH
whatsappNumberId on PATCH (the number cannot be changed after creation — delete and recreate)400 NUMBER_RESCOPE_NOT_SUPPORTED
Number outside your tenant404 NUMBER_NOT_FOUND
Webhook not visible to the key’s scope404 WEBHOOK_NOT_FOUND
The signing secret is never returned by any of these endpoints.

​
Dashboard

Everything above is also available in the dashboard at /webhooks: create/edit webhooks per number, pick events, pause/resume, and inspect delivery logs. The New/Edit Webhook UI includes the notice that message.read only fires when the recipient has WhatsApp read receipts enabled.