pinpoint-apm/pinpoint · error · IllegalArgumentException

Webhook URL resolves to a private address that is not allowe

Error message

Webhook URL resolves to a private address that is not allowed

What it means

validateResolvedAddress allows private addresses only when the host name matches the supplied WebhookHostPolicy allowlist (isAllowedPrivateHost). If the address is private but the host is not allowed by policy, this error is thrown. The policy intentionally matches host names only — an IP literal can never satisfy the allowlist, preventing callers from bypassing it.

Source

Thrown at commons-server/src/main/java/com/navercorp/pinpoint/common/server/webhook/WebhookUrlValidator.java:177

            throw new IllegalArgumentException("Webhook URL host is not allowed");
        }

        IPAddress address = toHostLiteralAddress(normalizedHost);
        if (address != null) {
            validateResolvedAddress(normalizedHost, address.toInetAddress(), WebhookHostPolicy.denyAll());
        }
    }

    public static void validateResolvedAddress(String host, InetAddress address, WebhookHostPolicy policy) {
        Objects.requireNonNull(policy, "policy");
        if (address == null) {
            throw new IllegalArgumentException("Webhook URL resolved address is required");
        }
        if (isBlockedAddress(address)) {
            throw new IllegalArgumentException("Webhook URL resolves to a non-public address");
        }
        if (isPrivateAddress(address) && !isAllowedPrivateHost(host, policy)) {
            throw new IllegalArgumentException("Webhook URL resolves to a private address that is not allowed");
        }
    }

    /**
     * The policy matches host names only. Allowing an IP literal to match would let a caller
     * reach an internal address without going through an allowed host name.
     */
    private static boolean isAllowedPrivateHost(String host, WebhookHostPolicy policy) {
        if (host == null) {
            return false;
        }
        String normalizedHost = normalizeHost(host);
        if (toHostLiteralAddress(normalizedHost) != null) {
            return false;
        }
        return policy.isAllowed(normalizedHost);
    }

View on GitHub (pinned to 744c3d3075)

Solutions

Add the specific internal host name to the WebhookHostPolicy allowlist for private addresses.
Use a host name (not an IP literal) so it can match the policy allowlist.
If the endpoint should be public, reconfigure it on a public address.

Example fix

// before
WebhookUrlValidator.validateResolvedAddress("internal.svc", addr, WebhookHostPolicy.denyAll());
// after
WebhookHostPolicy policy = WebhookHostPolicy.builder().allowPrivateHost("internal.svc").build();
WebhookUrlValidator.validateResolvedAddress("internal.svc", addr, policy);

Defensive patterns

Strategy: validation

Validate before calling

InetAddress addr = InetAddress.getByName(host);
if (addr.isSiteLocalAddress() && !policyAllows(host)) {
    throw new IllegalArgumentException("private address requires an allowlisted host: " + host);
}

Type guard

boolean privateHostAllowed(String host, WebhookHostPolicy p) { return p != null && p.allows(host); }

Try / catch

try {
    WebhookUrlValidator.validateResolvedAddress(host, addr, policy);
} catch (IllegalArgumentException e) {
    throw new ConfigurationException("Private webhook host not allowlisted: " + host);
}

Prevention

Always use host names (never IP literals) so the policy allowlist can match
Maintain an explicit allowlist of internal hosts that need webhooks
Document that policies match host names only, not IP literals

When it happens

Trigger: Calling validateResolvedAddress with a private address (e.g. 10.x.x.x, 192.168.x.x, 172.16-31.x.x) while isAllowedPrivateHost(host, policy) returns false — either no allowlist configured or the host name differs from policy entries; also IP-literal URLs, which are always denied.

Common situations: Pointing webhooks at internal on-prem services (10.x/192.168.x) without configuring the private-host allowlist, or using a raw IP literal hoping the allowlist matches.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/6a4a2e15286a05c3. Report an issue: GitHub.