pinpoint-apm/pinpoint · error · IllegalArgumentException

Webhook URL port is not allowed

Error message

Webhook URL port is not allowed

What it means

WebhookUrlValidator.validateAuthority rejects webhook URLs whose explicit port number is outside the legal 1-65535 range (port 0 or above MAX_PORT). Java's URI parser accepts these syntactically, so the validator enforces the RFC port bound before the URL is used for outbound webhook calls. It is a defensive SSRF/input-validation check.

Solutions

  1. Correct the port in the webhook URL to a value between 1 and 65535.
  2. If the port is intentionally default, remove the ':port' part entirely so uri.getPort() returns -1.
  3. Validate the port in configuration before passing the URL string to the validator (1 <= port <= 65535).

Example fix

// before
String url = "http://example.com:70000/webhook";
// after
String url = "http://example.com:8080/webhook";
Defensive patterns

Strategy: validation

Validate before calling

URI u = URI.create(url);
int port = u.getPort();
if (port != -1 && (port < 1 || port > 65535)) {
    throw new IllegalArgumentException("webhook port out of range: " + port);
}

Type guard

boolean isValidPort(URI u) { int p = u.getPort(); return p == -1 || (p >= 1 && p <= 65535); }

Try / catch

try {
    WebhookUrlValidator.validate(uri);
} catch (IllegalArgumentException e) {
    log.warn("Invalid webhook URL, rejecting: {}", e.getMessage());
}

Prevention

When it happens

Trigger: Calling WebhookUrlValidator.validateUriSyntax (via validate) with a URI whose getPort() returns 0 or a value > 65535, e.g. 'http://host:0/hook' or 'http://host:70000/hook'.

Common situations: Hand-edited webhook config where a port digit was mistyped (extra digit), templated URLs where an empty port placeholder rendered as 0, or programmatic URL construction with an uninitialized port variable.

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/5cf4f7fd2ef95907. Report an issue: GitHub.

Appendix: source

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

    private static void validateAuthority(URI uri) {
        if (uri.getHost() == null || uri.getHost().isBlank()) {
            throw new IllegalArgumentException("Webhook URL host is required");
        }
        if (isBlockedHostLiteral(uri.getHost())) {
            throw new IllegalArgumentException("Webhook URL host is not allowed");
        }
        if (uri.getRawUserInfo() != null) {
            throw new IllegalArgumentException("Webhook URL user info is not allowed");
        }
        if (uri.getRawFragment() != null) {
            throw new IllegalArgumentException("Webhook URL fragment is not allowed");
        }
        int port = uri.getPort();
        if (port == -1 && hasExplicitPort(uri)) {
            throw new IllegalArgumentException("Webhook URL port is not valid");
        }
        if (port == 0 || port > MAX_PORT) {
            throw new IllegalArgumentException("Webhook URL port is not allowed");
        }
    }

    private static boolean hasExplicitPort(URI uri) {
        String rawAuthority = uri.getRawAuthority();
        if (rawAuthority == null || rawAuthority.isEmpty()) {
            return false;
        }

        int hostStartIndex = rawAuthority.lastIndexOf('@') + 1;
        if (rawAuthority.charAt(hostStartIndex) == '[') {
            int hostEndIndex = rawAuthority.indexOf(']', hostStartIndex);
            return hostEndIndex >= 0
                    && hostEndIndex + 1 < rawAuthority.length()
                    && rawAuthority.charAt(hostEndIndex + 1) == ':';
        }
        return rawAuthority.indexOf(':', hostStartIndex) >= 0;
    }

View on GitHub (pinned to 744c3d3075)