Error codes

webhook_url_not_allowed

HTTP status: 422
Retry: No
Execution: Nothing was done
Admin needed: No

Webhook URL not allowed. A webhook URL must be an HTTPS URL on port 443, with no user name or password, whose host is not a RelationsAI host and resolves only to public internet addresses. The request schema already requires the URL to start with https://, so a URL with any other scheme is refused earlier with 400 validation_error (issue invalid_format) and never reaches this check. The URL is checked when the endpoint is created, when it is changed and again before every delivery; at delivery time a refusal is recorded on the delivery as blocked_destination instead.

What it means

The API returns HTTP 422 with error.code set to webhook_url_not_allowed. The default message is: "This URL cannot receive webhooks."

Common causes

port_not_allowed: the URL names a port other than 443.
credentials_in_url: the URL contains a user name or a password.
private_address: the host is, or resolves to, an address that is not on the public internet: private (10/8, 172.16/12, 192.168/16, fc00::/7), loopback, link-local (including cloud metadata addresses), shared (100.64/10), multicast, broadcast, unspecified, reserved, benchmarking or documentation ranges, or an IPv6 form that embeds an IPv4 address (IPv4-mapped, IPv4-compatible, NAT64, 6to4, Teredo). If any one of several resolved addresses is not public, the URL is refused.
invalid_host: the host cannot be resolved, is not a valid public host name (for example a single label such as localhost, or a local-only suffix such as .local or .internal), or is a RelationsAI host (relationsai.com or any of its subdomains).

How to identify it

Check the response status (422) and error.code (webhook_url_not_allowed). Branch on error.code, not on the message text: messages can be reworded, codes do not change within v1. Log error.request_id (also sent as the X-Request-Id header) so support can find the request.

How to fix it

Use a public HTTPS URL on port 443 that resolves only to public addresses. Authenticate deliveries by verifying the signature instead of putting credentials in the URL.

Retry guidance

Sending the request unchanged fails the same way. Fix the cause first (see How to fix it), then send it again.

Did anything happen?

This request was refused before any call was placed and before anything was charged.

Idempotency

Nothing was done and the refusal is not stored under the Idempotency-Key. Fix the cause, then send the same request (with the same key if you sent one).

Who can fix it

The developer who sends the request can fix it; no administrator action is normally needed.

When to contact support

If the error persists after the steps above, contact support@relationsai.com. See Support for what to include (the request_id, the time in UTC, the operation, and whether you used a test or live key) and what never to send (API keys, Authorization headers, webhook signing secrets, recording links, transcripts or customer data).

Example error response

JSON
{
  "error": {
    "code": "webhook_url_not_allowed",
    "message": "This URL cannot receive webhooks.",
    "details": {
      "reason": "private_address"
    },
    "request_id": "req_e3n52eyuduiy2nswlicrxtjh",
    "retry": "no",
    "doc_url": "https://docs.relationsai.com/errors/webhook_url_not_allowed"
  }
}

Operations that can return this error

POST /webhook-endpoints: Create a webhook endpoint
PATCH /webhook-endpoints/{webhook_endpoint_id}: Update a webhook endpoint

See all codes in the error-code reference.

telephony_disconnected precondition_required