webhook_url_invalid — Webhook URL rejected
What the API returns
{
"error": {
"code": "webhook_url_invalid",
"message": "The webhook URL is not reachable or not allowed.",
"request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
}
}Every Wapito error is this one envelope. Branch on code, which is stable; message is written for people and can be reworded; details appears only when there is something specific to say; request_id is what to quote to support.
What it means
webhook_url_invalid is an HTTP 422 error from the Wapito WhatsApp API: webhook URL rejected. The response message reads “The webhook URL is not reachable or not allowed.” It is retryable: the same request can succeed later without changes. 3 endpoints can raise it, POST /webhooks among them.
Why it happens
The endpoint you registered failed validation. Wapito requires a public HTTPS URL and refuses anything that points back into private space - localhost, loopback addresses, private ranges and link-local addresses are all blocked, because accepting them would turn the platform into a probe against its own network. A URL that is public but did not answer the verification request is refused for the same practical reason: events would be lost.
How to fix webhook_url_invalid
Use an https:// URL with a hostname that resolves publicly and a certificate that validates.
For local development, put a tunnel in front of your machine and register the tunnel's public URL rather than localhost.
Make sure the endpoint answers the verification request with a 2xx quickly; a slow endpoint behind a cold start is treated as unreachable.
Endpoints that raise it
Where you will meet it
- Connect a Number
Feature guide
Retry guidance
Safe to retry
The condition is transient, so the same request can succeed later without any change on your side. Retry with exponential backoff and jitter — start at one second, double each attempt, cap at a minute — and stop after a handful of tries so a stuck condition surfaces as an alert rather than a hot loop.
Frequently asked questions
Why is localhost blocked when it works for other APIs?
Because the request is made from our servers, not from your machine, so localhost there means our own host. Allowing it would let anyone use the webhook validator to probe internal services. Use a tunnel during development and swap the URL for your real endpoint before going live.
My URL is correct but still refused - what now?
Call the webhook test endpoint and watch your access log. The usual culprits are a certificate that only validates in a browser because of a missing intermediate, a firewall that allows your own country only, and a platform that cold-starts slower than the verification timeout.
Related
Try it on your own number
Create a channel, link a WhatsApp number by QR or pairing code, and call the API in a couple of minutes. The Sandbox plan is free and needs no card.