feat(cli): webhook configuration (#6555)

libs/cli/langgraph_cli/config.py

@@ -156,6 +156,8 @@ def validate_config(config: Config) -> Config:
         "auth": config.get("auth"),
         "encryption": config.get("encryption"),
         "http": config.get("http"),
+        # Pass through webhooks config so it can be injected into the image
+        "webhooks": config.get("webhooks"),
         "checkpointer": config.get("checkpointer"),
         "ui": config.get("ui"),
         "ui_config": config.get("ui_config"),
@@ -959,6 +961,10 @@ ADD {relpath} /deps/{name}
     if (http_config := config.get("http")) is not None:
         env_vars.append(f"ENV LANGGRAPH_HTTP='{json.dumps(http_config)}'")
 
+    # Inject webhooks configuration if provided
+    if (webhooks_config := config.get("webhooks")) is not None:
+        env_vars.append(f"ENV LANGGRAPH_WEBHOOKS='{json.dumps(webhooks_config)}'")
+
     if (checkpointer_config := config.get("checkpointer")) is not None:
         env_vars.append(
             f"ENV LANGGRAPH_CHECKPOINTER='{json.dumps(checkpointer_config)}'"
@@ -1085,6 +1091,10 @@ def node_config_to_docker(
     if (http_config := config.get("http")) is not None:
         env_vars.append(f"ENV LANGGRAPH_HTTP='{json.dumps(http_config)}'")
 
+    # Inject webhooks configuration if provided
+    if (webhooks_config := config.get("webhooks")) is not None:
+        env_vars.append(f"ENV LANGGRAPH_WEBHOOKS='{json.dumps(webhooks_config)}'")
+
     if (checkpointer_config := config.get("checkpointer")) is not None:
         env_vars.append(
             f"ENV LANGGRAPH_CHECKPOINTER='{json.dumps(checkpointer_config)}'"

libs/cli/langgraph_cli/schemas.py

@@ -362,7 +362,7 @@ class CorsConfig(TypedDict, total=False):
     """
 
 
-class ConfigurableHeaderConfig(TypedDict):
+class ConfigurableHeaderConfig(TypedDict, total=False):
     """Customize which headers to include as configurable values in your runs.
 
     By default, omits x-api-key, x-tenant-id, and x-service-key.
@@ -373,7 +373,7 @@ class ConfigurableHeaderConfig(TypedDict):
     """
 
     includes: list[str] | None
-    """Headers to include (if not also matches against an 'exludes' pattern.
+    """Headers to include (if not also matched against an 'excludes' pattern).
 
     Examples:
         - 'user-agent'
@@ -485,6 +485,46 @@ class HttpConfig(TypedDict, total=False):
     """
 
 
+class WebhookUrlPolicy(TypedDict, total=False):
+    require_https: bool
+    """Enforce HTTPS scheme for absolute URLs; reject `http://` when true."""
+    allowed_domains: list[str]
+    """Hostname allowlist. Supports exact hosts and wildcard subdomains.
+
+    Use entries like "hooks.example.com" or "*.mycorp.com". The wildcard only
+    matches subdomains ("foo.mycorp.com"), not the apex ("mycorp.com"). When
+    empty or omitted, any public host is allowed (subject to SSRF IP checks).
+    """
+    allowed_ports: list[int]
+    """Explicit port allowlist for absolute URLs.
+
+    If set, requests must use one of these ports. Defaults are respected when
+    a port is not present in the URL (443 for https, 80 for http).
+    """
+    max_url_length: int
+    """Maximum permitted URL length in characters; longer inputs are rejected early."""
+    disable_loopback: bool
+    """Disallow relative URLs (internal loopback calls) when true."""
+
+
+class WebhooksConfig(TypedDict, total=False):
+    env_prefix: str
+    """Required prefix for environment variables referenced in header templates.
+
+    Acts as an allowlist boundary to prevent leaking arbitrary environment
+    variables. Defaults to "LG_WEBHOOK_" when omitted.
+    """
+    url: WebhookUrlPolicy
+    """URL validation policy for user-supplied webhook endpoints."""
+    headers: dict[str, str]
+    """Static headers to include with webhook requests.
+
+    Values may contain templates of the form "${{ env.VAR }}". On startup, these
+    are resolved via the process environment after verifying `VAR` starts with
+    `env_prefix`. Mixed literals and multiple templates are allowed.
+    """
+
+
 class Config(TypedDict, total=False):
     """Top-level config for langgraph-cli or similar deployment tooling."""
 
@@ -613,6 +653,13 @@ class Config(TypedDict, total=False):
     and how cross-origin requests are handled.
     """
 
+    webhooks: WebhooksConfig | None
+    """Optional. Webhooks configuration for outbound event delivery.
+
+    Forwarded into the container as `LANGGRAPH_WEBHOOKS`. See `WebhooksConfig`
+    for URL policy and header templating details.
+    """
+
     ui: dict[str, str] | None
     """Optional. Named definitions of UI components emitted by the agent, each pointing to a JS/TS file.
     """