{"record":{"id":"f375b51c3fb47c39","repo":"openai/openai-python","slug":"the-webhook-secret-must-either-be-set-using-the-en","errorCode":null,"errorMessage":"The webhook secret must either be set using the env var, OPENAI_WEBHOOK_SECRET, on the client class, OpenAI(webhook_secret='123'), or passed to this function","messagePattern":"The webhook secret must either be set using the env var, OPENAI_WEBHOOK_SECRET, on the client class, OpenAI\\(webhook_secret='123'\\), or passed to this function","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/openai/resources/webhooks/webhooks.py","lineNumber":60,"sourceCode":"        payload: str | bytes,\n        headers: HeadersLike,\n        *,\n        secret: str | None = None,\n        tolerance: int = 300,\n    ) -> None:\n        \"\"\"Validates whether or not the webhook payload was sent by OpenAI.\n\n        Args:\n            payload: The webhook payload\n            headers: The webhook headers\n            secret: The webhook secret (optional, will use client secret if not provided)\n            tolerance: Maximum age of the webhook in seconds (default: 300 = 5 minutes)\n        \"\"\"\n        if secret is None:\n            secret = self._client.webhook_secret\n\n        if secret is None:\n            raise ValueError(\n                \"The webhook secret must either be set using the env var, OPENAI_WEBHOOK_SECRET, \"\n                \"on the client class, OpenAI(webhook_secret='123'), or passed to this function\"\n            )\n\n        if not _webhook_signature_matches(payload, headers, secret=secret, tolerance=tolerance):\n            raise InvalidWebhookSignatureError(\n                \"The given webhook signature does not match the expected signature\"\n            ) from None\n\n\nclass AsyncWebhooks(AsyncAPIResource):\n    def unwrap(\n        self,\n        payload: str | bytes,\n        headers: HeadersLike,\n        *,\n        secret: str | None = None,\n    ) -> UnwrapWebhookEvent:","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/openai/openai-python/blob/9917c6e28e66e90e1227b3d223c06a8c5441515a/src/openai/resources/webhooks/webhooks.py#L42-L78","documentation":"Webhooks.verify_signature needs the shared secret used to sign incoming webhook payloads. It first uses the explicitly passed secret, then falls back to the client's webhook_secret (populated from the OPENAI_WEBHOOK_SECRET env var or the webhook_secret constructor argument); if both are unset it raises this ValueError. This is a configuration error, not a payload problem.","triggerScenarios":"Calling client.webhooks.verify_signature(payload, headers) (or unwrap, which calls it) without passing secret while OPENAI_WEBHOOK_SECRET is unset and the client was constructed without webhook_secret='...'.","commonSituations":"Local development where the env var is only set in production, CI runs missing the secret, deploying with a different process manager that drops the environment, or forgetting to configure it after adding webhook handling.","solutions":["Set the OPENAI_WEBHOOK_SECRET environment variable where the app runs","Or pass the secret when constructing the client: OpenAI(webhook_secret='...')","Or pass secret=... directly to verify_signature/unwrap","Verify with print(os.environ.get('OPENAI_WEBHOOK_SECRET')) that the var is visible to the process"],"exampleFix":"# before\nclient = OpenAI()\nclient.webhooks.unwrap(payload, headers)\n\n# after\nclient = OpenAI(webhook_secret=os.environ[\"OPENAI_WEBHOOK_SECRET\"])\nevent = client.webhooks.unwrap(payload, headers)","handlingStrategy":"validation","validationCode":"secret = os.environ.get(\"OPENAI_WEBHOOK_SECRET\") or getattr(client, \"webhook_secret\", None)\nif not secret:\n    raise RuntimeError(\"Webhook secret not configured (set OPENAI_WEBHOOK_SECRET)\")","typeGuard":null,"tryCatchPattern":"try:\n    event = client.webhooks.unwrap(payload, headers)\nexcept ValueError as e:\n    if \"webhook secret\" in str(e):\n        return Response(\"Webhook not configured\", 503)\n    raise","preventionTips":["Set OPENAI_WEBHOOK_SECRET in every environment (dev, CI, prod)","Construct the client with webhook_secret loaded from a secrets manager","Fail fast at startup if the secret is missing instead of at first webhook"],"tags":["webhooks","signature-verification","missing-secret","configuration","env-var"],"backgroundTag":"missing-env-var","analyzedSha":"9917c6e28e66e90e1227b3d223c06a8c5441515a","analyzedAt":"2026-08-28T11:46:34.183Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}