bytedance/deer-flow · error · HTTPException

Webhook signature verification not configured. Set {_SECRET_

Error message

Webhook signature verification not configured. Set {_SECRET_ENV_VAR} or {_ALLOW_UNVERIFIED_ENV_VAR}=1 for unverified dev mode.

What it means

Raised by the GitHub webhook receiver with status 503 when neither the webhook secret env var (e.g. GITHUB_WEBHOOK_SECRET) nor the explicit dev bypass env var is set at delivery time. Normally the route is disabled at startup when unconfigured, so this fires only when the secret was cleared or rotated at runtime without a Gateway restart — the endpoint refuses to accept unverifiable deliveries rather than silently skipping signature checks.

Source

Thrown at backend/app/gateway/routers/github_webhooks.py:235

    the explicit unverified opt-in, return 503 rather than accept a
    forgeable delivery.
    """
    body = await request.body()

    secret = _get_webhook_secret()
    if secret is None:
        if not _unverified_webhooks_allowed():
            # Should be unreachable if startup-time is_route_enabled() was honored,
            # but a runtime rotation that cleared the secret without a restart
            # would land here. Refuse the delivery.
            logger.error(
                "github_webhook: %s is not set and %s=1 not set; rejecting delivery (event=%s delivery=%s)",
                _SECRET_ENV_VAR,
                _ALLOW_UNVERIFIED_ENV_VAR,
                x_github_event,
                x_github_delivery,
            )
            raise HTTPException(
                status_code=503,
                detail=f"Webhook signature verification not configured. Set {_SECRET_ENV_VAR} or {_ALLOW_UNVERIFIED_ENV_VAR}=1 for unverified dev mode.",
            )
        logger.warning(
            "github_webhook: accepting UNVERIFIED delivery (event=%s delivery=%s). %s=1 is set — dev/loopback mode ONLY. Do not use in production.",
            x_github_event,
            x_github_delivery,
            _ALLOW_UNVERIFIED_ENV_VAR,
        )
    else:
        if not _verify_signature(secret, body, x_hub_signature_256):
            logger.warning(
                "github_webhook: signature verification FAILED (event=%s delivery=%s)",
                x_github_event,
                x_github_delivery,
            )
            raise HTTPException(status_code=401, detail="Invalid or missing X-Hub-Signature-256")

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Set the webhook secret env var (GITHUB_WEBHOOK_SECRET or the repo's documented _SECRET_ENV_VAR) matching the GitHub App/webhook configuration and restart the Gateway.
2. For local loopback development only, set the allow-unverified env var (e.g. DEERFLOW_GITHUB_WEBHOOK_ALLOW_UNVERIFIED=1) to accept unsigned deliveries — never in production.
3. After any secret rotation, restart the Gateway so startup-time route enablement and runtime secret state agree.

Example fix

# before
# (secret cleared at runtime, no restart)
curl -i https://host/api/webhooks/github -d '{}'
# -> 503 Webhook signature verification not configured

# after
export GITHUB_WEBHOOK_SECRET="$(gh api repos/:owner/:repo --jq .hooks_url >/dev/null; printf '%s' "$MY_WEBHOOK_SECRET")"
systemctl restart deerflow-gateway  # or: make stop && make dev

# preflight: refuse to start/declare route ready without secret or explicit dev bypass
: "${GITHUB_WEBHOOK_SECRET:?GITHUB_WEBHOOK_SECRET required for webhook route}"

try { await postWebhook(payload); } catch (e) { if (e.status === 503 && /not configured/.test(e.detail)) alert('Webhook secret missing on server — fix config and restart'); throw e; }

When it happens

Trigger: Rotating GITHUB_WEBHOOK_SECRET to empty in the environment/config without restarting the Gateway; a config reload path that nulls the secret while the route stays mounted; misconfigured deployment where the secret is injected into some replicas but not others.

Common situations: Kubernetes secret rotation that empties a value; CI/staging containers missing the secret env var; operators toggling the unverified-dev-mode flag off but forgetting to re-add the secret before GitHub redelivers webhooks.

Related errors

• Neither GITHUB_APP_PRIVATE_KEY nor GITHUB_APP_PRIVATE_KEY_PA
• Invalid or missing X-Hub-Signature-256
• Missing X-GitHub-Event header
• Invalid JSON body
• fan-out failed for delivery {x_github_delivery!r}: {exc!r}

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/0c52dadbf97b6384. Report an issue: GitHub.