mastra-ai/mastra · error · Error

WorkOS webhook secret is required. Provide it in options or

Error message

WorkOS webhook secret is required. Provide it in options or set WORKOS_WEBHOOK_SECRET environment variable.

What it means

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.

Source

Thrown at auth/workos/src/directory-sync.ts:88

 */
export class WorkOSDirectorySync {
  private workos: WorkOS;
  private webhookSecret: string;
  private handlers: DirectorySyncHandlers;

  /**
   * Creates a new WorkOSDirectorySync instance.
   *
   * @param workos - WorkOS client instance
   * @param options - Configuration options including webhook secret and event handlers
   * @throws Error if webhook secret is not provided
   */
  constructor(workos: WorkOS, options: WorkOSDirectorySyncOptions) {
    this.workos = workos;

    const webhookSecret = options.webhookSecret ?? process.env.WORKOS_WEBHOOK_SECRET;
    if (!webhookSecret) {
      throw new Error(
        'WorkOS webhook secret is required. Provide it in options or set WORKOS_WEBHOOK_SECRET environment variable.',
      );
    }

    this.webhookSecret = webhookSecret;
    this.handlers = options.handlers;
  }

  /**
   * Handles incoming webhook events from WorkOS Directory Sync.
   *
   * This method verifies the webhook signature for security, parses the event,
   * and routes it to the appropriate handler based on the event type.
   *
   * @param payload - Raw webhook payload (string or object)
   * @param signature - WorkOS signature header for verification
   * @throws Error if signature verification fails
   */

View on GitHub (pinned to 75dd419e61)

Solutions

1. Copy the webhook signing secret from the WorkOS dashboard (Directory Sync > Configuration) and set WORKOS_WEBHOOK_SECRET
2. Pass it explicitly: new WorkOSDirectorySync(workos, { webhookSecret: '...', handlers })
3. Confirm the env var is loaded in the process running directory sync
4. Rotate/update the secret in both WorkOS dashboard and your env together

Example fix

// before
const ds = new WorkOSDirectorySync(workos, { handlers });
// after
const ds = new WorkOSDirectorySync(workos, {
  webhookSecret: process.env.WORKOS_WEBHOOK_SECRET,
  handlers,
});

function assertWebhookSecret(opts) {
  const secret = opts?.webhookSecret ?? process.env.WORKOS_WEBHOOK_SECRET;
  if (!secret) throw new Error('WORKOS_WEBHOOK_SECRET missing: copy it from WorkOS dashboard > Directory Sync');
  return secret;
}

function hasWebhookSecret(o) {
  return typeof o === 'object' && o !== null && typeof o.webhookSecret === 'string' && o.webhookSecret.length > 0;
}

try {
  ds = new WorkOSDirectorySync(workos, options);
} catch (e) {
  if (e.message.includes('webhook secret is required')) {
    throw new ConfigError('Set WORKOS_WEBHOOK_SECRET to the signing secret from the WorkOS dashboard');
  }
  throw e;
}

When it happens

Trigger: `new WorkOSDirectorySync(workos, options)` where options.webhookSecret is undefined and process.env.WORKOS_WEBHOOK_SECRET is unset or empty.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• WorkOS API key and client ID are required. Provide them in t
• WorkOS API key and client ID are required. Provide them in t
• Okta domain is required. Provide it in the options or set OK
• Okta API token is required for RBAC. Provide it in the optio
• Supabase URL and anon key are required, please provide them

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/be88ca71f5531904. Report an issue: GitHub.