What causes "callback_url must be an absolute http(s) URL" in calesthio/OpenMontage?

Set the value to a fully-qualified absolute URL: https://host.example.com/path

calesthio/OpenMontage · error · ValueError

callback_url must be an absolute http(s) URL

Error message

callback_url must be an absolute http(s) URL

What it means

ValueError raised by validate_callback_url when a non-empty callback_url parses without an http/https scheme or without a netloc. It is a cheap, dependency-free pre-flight check: Kling will silently ignore or reject malformed webhook URLs, so obviously-invalid input is caught client-side before any API call. Empty/None passes through as None (callback disabled).

Source

Thrown at tools/_kling/callbacks.py:16

"""Callback validation helpers for Kling official providers."""

from __future__ import annotations

from urllib.parse import urlparse


def validate_callback_url(callback_url: str | None) -> str | None:
    """Return a normalized callback URL or raise for obviously invalid input."""

    if not callback_url:
        return None
    value = str(callback_url).strip()
    parsed = urlparse(value)
    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
        raise ValueError("callback_url must be an absolute http(s) URL")
    return value

View on GitHub (pinned to 95e1c3d0ab)

Solutions

Set the value to a fully-qualified absolute URL: https://host.example.com/path
Check template/env interpolation actually produced the host before building the URL
For local testing use a tunnel (ngrok/cloudflared) and pass its absolute https URL — Kling must be able to reach the callback
Leave callback_url unset/None when no callback is needed — that is a valid no-callback path

Example fix

# before
validate_callback_url("kling-hooks.example.com/cb")  # raises

# after
validate_callback_url("https://kling-hooks.example.com/cb")  # ok

Defensive patterns

Strategy: validation

Validate before calling

from urllib.parse import urlparse
def is_valid_callback_url(url: str | None) -> bool:
    if not url:
        return True  # unset is fine
    p = urlparse(str(url).strip())
    return p.scheme in {"http", "https"} and bool(p.netloc)

if not is_valid_callback_url(callback_url):
    raise SystemExit("callback_url must be absolute http(s), e.g. https://host/hook")

Type guard

def is_valid_callback_url(url: str | None) -> bool:
    if not url:
        return True
    p = urlparse(str(url).strip())
    return p.scheme in {"http", "https"} and bool(p.netloc)

Try / catch

try:
    validate_callback_url(callback_url)
except ValueError:
    raise SystemExit("fix callback_url: include scheme and host, or unset it")

Prevention

Build callback URLs with a base URL from config, never string-concat paths alone
Assert interpolated env vars (host) are non-empty before composing the URL
Use a tunnel for local webhook testing; Kling must reach the callback

When it happens

Trigger: Passing callback_url values like 'kling-hook.example.com/webhook' (no scheme), 'http://' (no host), 'file:///tmp/x', relative paths, or values with leading whitespace that still strip to scheme-less strings.

Common situations: Config files storing the webhook without https:// because the ingress adds it later; localhost URLs typed without scheme during local testing; template interpolation producing empty host ('https://${HOST}/hook' with unset HOST); copying a path-only webhook route from docs.

Related errors

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/ad7e7273bac33f78. Report an issue: GitHub.