Skip to Content
Developers

Webhooks

Receive inbound messages and status changes on your own URLs.

Each number has three webhook URLs, each optional. An unset URL means that flow is not delivered.

FieldReceives
inbound_webhookMessages users send to the number.
status_webhookStatus changes of the messages you sent: delivered, read, failed.
outbound_webhookEach message sent from the number, and each send that failed.

Configure

PATCH/v1/numbers/{phone_number}/webhooksReference →

PATCH changes only the fields you send. null disables a flow.

curl -X PATCH "$WAPIU_API/v1/numbers/$WAPIU_NUMBER/webhooks" \  -H "Authorization: Bearer $WAPIU_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "inbound_webhook": "https://example.com/wapiu/inbound",    "status_webhook": "https://example.com/wapiu/status"  }'
{
  "phone_number": "393401234567",
  "inbound_webhook": "https://example.com/wapiu/inbound",
  "outbound_webhook": null,
  "status_webhook": "https://example.com/wapiu/status",
  "created_at": "2026-11-22T10:00:00Z",
  "updated_at": "2026-11-22T10:00:00Z"
}
MethodEffect
GETRead the configuration. 404 if none is set.
PATCHChange the fields you send.
PUTReplace the configuration: omitted fields become null.
DELETERemove the configuration. 204.

URLs must start with http:// or https://, up to 255 characters. A change can take up to a minute to apply.

Delivery

Each event is a POST with a JSON body and these headers:

HeaderDescription
Content-Typeapplication/json
X-WaQ-Event-IdUnique ID of the event.
X-WaQ-SubjectThe event type.
Your answerResult
2xxDelivered.
408, 429, 5xx, timeout, connection errorRetried later.
Any other 4xxDropped, not retried.

Delivery is at least once: the same event can arrive more than once. Deduplicate on X-WaQ-Event-Id. The timeout is 10 seconds: answer first, process afterwards.

Event body not yet versioned

The event body may still change, and requests are not signed yet. Both are coming: a versioned body and an HMAC signature header.

On this page