pinpoint-apm/pinpoint · error · IllegalArgumentException

Webhook URL scheme is required

Error message

Webhook URL scheme is required

What it means

WebhookUrlValidator.validateScheme throws IllegalArgumentException when the parsed URI has no scheme component. The URL must declare http or https explicitly; a scheme-less URL cannot be dereferenced as an HTTP webhook target.

Source

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

        final URI uri;

        try {
            uri = new URI(url).normalize().parseServerAuthority();
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException("Malformed webhook URL", e);
        }

        validateScheme(uri);
        validateAuthority(uri);

        return uri;
    }

    private static void validateScheme(URI uri) {
        String scheme = uri.getScheme();
        if (scheme == null) {
            throw new IllegalArgumentException("Webhook URL scheme is required");
        }

        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");
        }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Prefix the URL with an explicit scheme: https://example.com/hook
2. Normalize user input: if the string lacks '://', prepend 'https://' before validating
3. Note that 'localhost:8080/hook' parses scheme='localhost' — use 'http://localhost:8080/hook'

Example fix

// before
validator.validateSyntax("example.com/hook");
// after
validator.validateSyntax("https://example.com/hook");

if (!url.matches("^https?://.*")) url = "https://" + url;

boolean hasHttpScheme(java.net.URI uri) { String s = uri.getScheme(); return "http".equalsIgnoreCase(s) || "https".equalsIgnoreCase(s); }

try { WebhookUrlValidator.validateSyntax(url); } catch (IllegalArgumentException e) { if (e.getMessage().contains("scheme")) { hint = "add https:// prefix"; } }

When it happens

Trigger: Passing a URL like 'example.com/hook' or '//example.com/hook' (protocol-relative) to validateSyntax/uri — the URI parses but getScheme() returns null.

Common situations: Users entering host-only endpoints in webhook config assuming https is implied; protocol-relative URLs copied from browser-facing code; config values like 'localhost:8080/hook' where 'localhost' is parsed as the scheme.

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 must be http or https
• Webhook URL host is required
• Webhook URL fragment is not allowed

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