{"record":{"id":"be88ca71f5531904","repo":"mastra-ai/mastra","slug":"workos-webhook-secret-is-required-provide-it-in-o","errorCode":null,"errorMessage":"WorkOS webhook secret is required. Provide it in options or set WORKOS_WEBHOOK_SECRET environment variable.","messagePattern":"WorkOS webhook secret is required\\. Provide it in options or set WORKOS_WEBHOOK_SECRET environment variable\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"auth/workos/src/directory-sync.ts","lineNumber":88,"sourceCode":" */\nexport class WorkOSDirectorySync {\n  private workos: WorkOS;\n  private webhookSecret: string;\n  private handlers: DirectorySyncHandlers;\n\n  /**\n   * Creates a new WorkOSDirectorySync instance.\n   *\n   * @param workos - WorkOS client instance\n   * @param options - Configuration options including webhook secret and event handlers\n   * @throws Error if webhook secret is not provided\n   */\n  constructor(workos: WorkOS, options: WorkOSDirectorySyncOptions) {\n    this.workos = workos;\n\n    const webhookSecret = options.webhookSecret ?? process.env.WORKOS_WEBHOOK_SECRET;\n    if (!webhookSecret) {\n      throw new Error(\n        'WorkOS webhook secret is required. Provide it in options or set WORKOS_WEBHOOK_SECRET environment variable.',\n      );\n    }\n\n    this.webhookSecret = webhookSecret;\n    this.handlers = options.handlers;\n  }\n\n  /**\n   * Handles incoming webhook events from WorkOS Directory Sync.\n   *\n   * This method verifies the webhook signature for security, parses the event,\n   * and routes it to the appropriate handler based on the event type.\n   *\n   * @param payload - Raw webhook payload (string or object)\n   * @param signature - WorkOS signature header for verification\n   * @throws Error if signature verification fails\n   */","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/auth/workos/src/directory-sync.ts#L70-L106","documentation":"The WorkOS directory-sync feature verifies incoming webhook signatures with a shared secret. WorkOSDirectorySync's constructor resolves it from options.webhookSecret or WORKOS_WEBHOOK_SECRET; without it webhooks cannot be authenticated, so construction throws.","triggerScenarios":"`new WorkOSDirectorySync(workos, options)` where options.webhookSecret is undefined and process.env.WORKOS_WEBHOOK_SECRET is unset or empty.","commonSituations":"Directory sync enabled but webhook secret from WorkOS dashboard never copied to env; secret manager missing the key in a new environment; webhook configured in WorkOS but secret option omitted in code.","solutions":["Copy the webhook signing secret from the WorkOS dashboard (Directory Sync > Configuration) and set WORKOS_WEBHOOK_SECRET","Pass it explicitly: new WorkOSDirectorySync(workos, { webhookSecret: '...', handlers })","Confirm the env var is loaded in the process running directory sync","Rotate/update the secret in both WorkOS dashboard and your env together"],"exampleFix":"// before\nconst ds = new WorkOSDirectorySync(workos, { handlers });\n// after\nconst ds = new WorkOSDirectorySync(workos, {\n  webhookSecret: process.env.WORKOS_WEBHOOK_SECRET,\n  handlers,\n});","handlingStrategy":"validation","validationCode":"function assertWebhookSecret(opts) {\n  const secret = opts?.webhookSecret ?? process.env.WORKOS_WEBHOOK_SECRET;\n  if (!secret) throw new Error('WORKOS_WEBHOOK_SECRET missing: copy it from WorkOS dashboard > Directory Sync');\n  return secret;\n}","typeGuard":"function hasWebhookSecret(o) {\n  return typeof o === 'object' && o !== null && typeof o.webhookSecret === 'string' && o.webhookSecret.length > 0;\n}","tryCatchPattern":"try {\n  ds = new WorkOSDirectorySync(workos, options);\n} catch (e) {\n  if (e.message.includes('webhook secret is required')) {\n    throw new ConfigError('Set WORKOS_WEBHOOK_SECRET to the signing secret from the WorkOS dashboard');\n  }\n  throw e;\n}","preventionTips":["Copy the signing secret when you configure the webhook in WorkOS, in the same change","Add the var to the deployment secret checklist","Rotate dashboard and env secret together","Only enable directory sync in environments where the secret is provisioned"],"tags":["config","env-var","workos","webhook","directory-sync"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}