pinpoint-apm/pinpoint · error · IllegalArgumentException

Webhook URL fragment is not allowed

Error message

Webhook URL fragment is not allowed

What it means

WebhookUrlValidator.validateAuthority throws IllegalArgumentException when the URL contains a fragment (rawFragment != null, the '#...' part). Fragments are client-side only and never sent to the server, so they are meaningless — and potentially misleading — in a webhook target URL.

Source

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

        String normalizedScheme = scheme.toLowerCase(Locale.ROOT);
        if (!"http".equals(normalizedScheme) && !"https".equals(normalizedScheme)) {
            throw new IllegalArgumentException("Webhook URL scheme must be http or https");
        }
    }

    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) == '[') {

View on GitHub (pinned to 744c3d3075)

Solutions

1. Strip the '#fragment' portion from the URL before validating/saving
2. If the fragment encoded meaningful routing info, move it into the path or query string

Example fix

// before
validator.validateSyntax("https://example.com/webhook#setup");
// after
validator.validateSyntax("https://example.com/webhook");

int hash = url.indexOf('#'); if (hash >= 0) url = url.substring(0, hash);

boolean hasNoFragment(java.net.URI uri) { return uri.getRawFragment() == null; }

try { WebhookUrlValidator.validateSyntax(url); } catch (IllegalArgumentException e) { if (e.getMessage().contains("fragment")) { strip '#...' and retry; } }

When it happens

Trigger: URLs like 'https://example.com/hook#section' or copied URLs that carried an anchor, passed to validateSyntax/uri.

Common situations: Copying a URL from a browser address bar or docs page that included an anchor link; templating mistakes appending '#...' placeholders.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Webhook URL is required
• Malformed webhook URL
• Webhook URL scheme is required
• Webhook URL scheme must be http or https
• Webhook URL host is required

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