infiniflow/ragflow · error · Exception

Webhook security is required. Set allow_anonymous to true to

Error message

Webhook security is required. Set allow_anonymous to true to permit unauthenticated webhooks.

What it means

The webhook endpoint's validate_webhook_security requires a non-empty dict as the agent's security configuration (api/apps/restful_apis/agent_api.py:1892). A missing, None, empty, or non-dict security_cfg logs a warning and raises Exception('Webhook security is required. Set allow_anonymous to true to permit unauthenticated webhooks.'). Unauthenticated webhooks are denied by default.

Source

Thrown at api/apps/restful_apis/agent_api.py:1892

    if not webhook_cfg:
        return get_data_error_result(code=RetCode.BAD_REQUEST, message="Webhook not configured for this agent."), RetCode.BAD_REQUEST

    # 5. Validate request method against webhook_cfg.methods
    allowed_methods = webhook_cfg.get("methods", [])
    request_method = request.method.upper()
    if allowed_methods and request_method not in allowed_methods:
        return get_data_error_result(code=RetCode.BAD_REQUEST, message=f"HTTP method '{request_method}' not allowed for this webhook."), RetCode.BAD_REQUEST

    async def validate_webhook_security(security_cfg: dict):
        """Validate webhook security rules based on security configuration."""

        if not isinstance(security_cfg, dict) or not security_cfg:
            logging.warning(
                "Webhook denied: missing security config agent_id=%s method=%s",
                agent_id,
                request.method,
            )
            raise Exception("Webhook security is required. Set allow_anonymous to true to permit unauthenticated webhooks.")

        # 1. Validate max body size
        await _validate_max_body_size(security_cfg)

        # 2. Validate IP whitelist
        _validate_ip_whitelist(security_cfg)

        # # 3. Validate rate limiting
        _validate_rate_limit(security_cfg)

        # 4. Validate authentication
        auth_type = security_cfg.get("auth_type", "none")

        if auth_type == "none":
            if not _allow_anonymous_webhook(security_cfg):
                logging.warning(
                    "Webhook denied: anonymous access missing explicit opt-in agent_id=%s method=%s",
                    agent_id,

View on GitHub (pinned to 554fb1133a)

Solutions

1. Add a security configuration object to the webhook agent (auth_type plus its required fields, e.g. token/basic/jwt).
2. If the webhook is intentionally public, set allow_anonymous: true inside the security config to explicitly opt in.
3. Re-save/publish the agent after editing so the running webhook picks up the new security config.
4. Inspect the request payload you send - the error is server-side config, not headers; headers matter only after a security block exists.

Example fix

// before: agent webhook config
"security": {}

// after
"security": {"auth_type": "token", "token": "s3cr3t...", "allow_anonymous": false}

security_cfg = agent_config.get("webhook", {}).get("security")
if not isinstance(security_cfg, dict) or not security_cfg:
    raise ValueError("Webhook requires a security config; set allow_anonymous=true only if public access is intended")

def has_webhook_security(cfg: dict) -> bool:
    sec = cfg.get("webhook", {}).get("security")
    return isinstance(sec, dict) and len(sec) > 0

try:
    resp = await invoke_webhook(session, url, payload)
except WebhookRejected as e:
    if "security is required" in str(e):
        raise ConfigError("Configure webhook security on the agent before calling it") from e
    raise

When it happens

Trigger: Publishing/running an agent as a webhook without any security block in its configuration; security_cfg serialized as null or {} (e.g. a template agent, or an API client that strips the field); sending a test request right after creating a webhook before configuring security.

Common situations: Quick trial of the webhook feature skipping the security step; agent JSON imported from a template without a security section; automation tools that drop empty objects on export.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Anonymous webhook access requires allow_anonymous to be true
• Unsupported auth_type: {auth_type}
• Failed to load configured SSH known_hosts file.
• Dataset({nm_or_id}) does not exist.
• No dataset is selected.

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/dcbab428a5fd7ad6. Report an issue: GitHub.