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).

Pilot Status Webhooks page — The Webhooks page — create, edit, deactivate, or delete a webhook and inspect its delivery events.

For payloads and the full event list, see the event reference.

Endpoints

Method	Endpoint	Description
`GET`	`/v1/webhooks`	List the webhooks visible to the key’s scope.
`POST`	`/v1/webhooks`	Create 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}/logs`	Recent 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"] }'

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"

Reading delivery logs

GET /v1/webhooks/{id}/logs returns the recent attempts, newest first. Two fields together tell you where an attempt died:

`status`	`statusCode`	`response`
`SUCCESS`	the HTTP status (2xx)	your endpoint’s body, truncated to 1000 characters
`FAILED`	the HTTP status	your endpoint’s body — it answered, but not with a 2xx
`FAILED`	`null`	the request never completed; `response` holds the reason chain

A statusCode of null is the case worth reading closely: nothing reached your server, so no status exists. response then carries the chain of causes, outermost first, joined by <- and tagged with the system error code:

fetch failed <- getaddrinfo EAI_AGAIN hooks.example.com [EAI_AGAIN]
fetch failed <- connect ECONNREFUSED 203.0.113.10:443 [ECONNREFUSED]
The operation was aborted due to timeout

The codes that show up most often:

Code	What it means
`EAI_AGAIN`, `ENOTFOUND`	your hostname did not resolve
`ECONNREFUSED`	the host answered but nothing is listening on that port
`ECONNRESET`	the connection was closed mid-request
`CERT_HAS_EXPIRED`, `DEPTH_ZERO_SELF_SIGNED_CERT`	TLS was rejected
(no code, “aborted due to timeout”)	your endpoint did not answer in time

Treat response as a diagnostic string, not a contract. The wording comes from the runtime and can change between releases; branch on status and statusCode, and read response when you need to know why.

A failed attempt is retried with exponential backoff before it is given up on, so a single FAILED row does not mean the event was lost — look for a later SUCCESS on the same event.

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

Rule	Error
Create without a number (tenant-scoped key, no `whatsappNumberId` / header)	400 `NUMBER_REQUIRED`
`whatsappNumberId` differs from a number-scoped key’s number	400 `NUMBER_MISMATCH`
`whatsappNumberId` on `PATCH` (the number cannot be changed after creation — delete and recreate)	400 `NUMBER_RESCOPE_NOT_SUPPORTED`
Number outside your tenant	404 `NUMBER_NOT_FOUND`
Webhook not visible to the key’s scope	404 `WEBHOOK_NOT_FOUND`

The signing secret is never returned by any of these endpoints.

How many webhooks per number

A number can carry more than one webhook. Scoping is many-to-many: every active webhook subscribed to the number receives the events it subscribed to, and a second one does not replace the first. Use that to split concerns — one endpoint for conversations, another for health and monitoring. The single refusal is an exact duplicate: the same url on the same number — 409 WEBHOOK_DUPLICATE. There is no legitimate reason for two, and the integration that created instead of updating used to pile up rows in silence; it now gets a conflict. A workspace-wide cap of 50 webhooks also applies (409 WEBHOOK_LIMIT_REACHED) — deliberately loose, since a tenant with many numbers may want one per number.

Two endpoints on the same number

# 1) conversations → your inbox / helpdesk
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/inbox", "name": "Inbox", "events": ["messages", "smb_message_echoes"] }'

# 2) everything → your monitoring endpoint (this is the ONLY way to get the
#    number-health family; see the event reference)
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/monitor", "name": "Monitor", "events": ["*"] }'

Verify the signature

Every webhook created from 2026-09-15 onward is signed by birth. Creation mints a secret and returns it in clear on that 201 — the only response in the life of a secret that carries it. Nothing reads it back.

Webhooks created before that date have no secret, and stay that way. Their deliveries still go out unsigned. That is deliberate: switching signature verification on underneath a live integration is its own outage. POST /v1/webhooks/{id}/rotate-secret is how you turn it on for one of them — and the only way to recover a secret that was lost, since no read returns it.Read hasSecret on any webhook to tell the two apart before you decide whether your receiver can reject unsigned deliveries.

Rotate — or mint one for an older webhook

curl -X POST "https://pilotstatus.com.br/v1/webhooks/wh_abc/rotate-secret" \
  -H "x-api-key: ps_your_token_here"
# → { "id": "wh_abc", "hasSecret": true, "secret": "…" }   ← in clear, once

Rotation is immediate and has no overlap window. The previous secret stops verifying the moment the call returns; deliveries already in flight sign with whichever value their dispatch loaded. Accept either secret on your side for a minute, or rotate while the number is quiet.

When a secret is set, the header x-pilot-status-signature carries the hex-encoded HMAC-SHA256 of the raw request body, keyed with the secret. Compute the HMAC over the raw bytes exactly as received (before any JSON parsing) and compare in constant time:

Node

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

Deduplicate retries: `Idempotency-Key`

When it is present, Idempotency-Key is stable per event: a retry, a backoff replay and a failover replay of the same event all carry the same value, so it is the right key to dedupe on. The same value is also merged into the delivered JSON body as a top-level idempotencyKey field, so you can read it from either place.

The header is not on every delivery. It is derived from a message id found in the payload (messageId / internalMessageId, at the top level or under data). A payload with no such id gets no header and no body field — that includes:

every Meta Cloud API native envelope (messages, smb_message_echoes, message_echoes, the template and account fields …), whose top level is { object, entry },
the number.* lifecycle and number-health events.

So a Meta number’s conversation traffic is not covered by this header today. Dedupe those on Meta’s own ids instead — and read the wamid warning in the event reference before keying on the wamid alone.

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.

Overview

Messaging

Templates

Numbers

Phone Lines

Conversations & Data

Webhooks

Voice Calls

API Layer

Account & Billing

Branding & Embedding

Configure Webhooks in Pilot Status — API and Dashboard

Configure webhooks

Endpoints

Number scoping

Examples

Reading delivery logs

Event gating

Rules and errors

How many webhooks per number

Verify the signature

Rotate — or mint one for an older webhook

Deduplicate retries: `Idempotency-Key`

Dashboard

​Configure webhooks

​Endpoints

​Number scoping

​Examples

​Reading delivery logs

​Event gating

​Rules and errors

​How many webhooks per number

​Verify the signature

​Rotate — or mint one for an older webhook

​Deduplicate retries: Idempotency-Key

​Dashboard

Configure webhooks

Endpoints

Number scoping

Examples

Reading delivery logs

Event gating

Rules and errors

How many webhooks per number

Verify the signature

Rotate — or mint one for an older webhook

Deduplicate retries: `Idempotency-Key`

Dashboard