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.
| Field | Receives |
|---|---|
inbound_webhook | Messages users send to the number. |
status_webhook | Status changes of the messages you sent: delivered, read, failed. |
outbound_webhook | Each 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"
}| Method | Effect |
|---|---|
GET | Read the configuration. 404 if none is set. |
PATCH | Change the fields you send. |
PUT | Replace the configuration: omitted fields become null. |
DELETE | Remove 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:
| Header | Description |
|---|---|
Content-Type | application/json |
X-WaQ-Event-Id | Unique ID of the event. |
X-WaQ-Subject | The event type. |
| Your answer | Result |
|---|---|
2xx | Delivered. |
408, 429, 5xx, timeout, connection error | Retried later. |
Any other 4xx | Dropped, 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.