Better Auth Sync Plugin for Webhooks

Common errors

• TypeError: Cannot read properties of undefined (reading 'APP_ORIGIN')

  cause Environment variable `APP_ORIGIN` is not defined or accessible where `convexJwt` is configured.
  fix Ensure `APP_ORIGIN` is correctly set in your environment variables for the Better Auth server. For Node.js, this typically means `process.env.APP_ORIGIN`.

• Response with status 401 from webhook endpoint

  cause The `verifyWebhook` function in your Convex HTTP route failed, likely due to a mismatch in `WEBHOOK_SECRET` or an invalid signature/timestamp in the incoming webhook request.
  fix Verify that `process.env.WEBHOOK_SECRET` in your `convex/http.ts` matches the `secret` configured in the `syncPlugin` on your Better Auth server. Also, check for clock skew between the Better Auth server and Convex.

• Convex `ConvexProviderWithAuth` or `useAuth` hook not working as expected, authentication state is missing.

  cause The `createConvexBetterAuth` setup in your `src/providers/convex-provider.tsx` is incorrect, or `authClient` is not properly initialized, preventing the auth context from being provided.
  fix Double-check that `authClient` from `@/lib/auth-client` is correctly configured and that `ConvexClientProvider` is wrapping your application's components at a high level in the React tree.

Warnings

• gotcha Mismatch between `applicationID` in `convex/auth.config.ts` and `issuer`/`audience` in `convexJwt` will cause JWT validation failures, preventing users from being authenticated correctly via Convex. This is a common misconfiguration point.
  Fix: Ensure `applicationID` in `convex/auth.config.ts` exactly matches the `issuer` and `audience` values provided to `convexJwt` plugin. Both typically derive from `process.env.APP_ORIGIN`.
• gotcha The `WEBHOOK_SECRET` environment variable must be a long, random, and securely stored string. If exposed or easily guessable, it could allow unauthorized parties to send forged authentication events to your Convex backend, leading to data corruption or security vulnerabilities.
  Fix: Generate a strong, unpredictable secret using a secure random string generator. Store it in environment variables and never commit it to source control. Rotate secrets regularly.
• gotcha Incorrect configuration of HTTP routes in Convex for `/auth-webhook` or `/.well-known/jwks.json` will prevent the sync plugin from functioning or JWTs from being validated. Missing routes or incorrect methods/handlers will lead to 404/405 errors.
  Fix: Carefully follow the documentation for setting up the HTTP routes in `convex/http.ts`, ensuring correct paths, methods (`POST` for webhook, `GET` for JWKS), and handler functions (`verifyWebhook`, `fetchJwks`).
• gotcha The package is in version `0.2.0`, indicating it's still under active development and not yet at a stable 1.0.0 release. Minor versions might introduce breaking changes without a major version bump, though semver would dictate otherwise. Expect API adjustments in future updates.
  Fix: Pin exact versions (`~0.2.0` or `0.2.0`) rather than caret ranges (`^0.2.0`) in your `package.json` to prevent unexpected breaking changes on patch/minor updates. Review release notes carefully when upgrading.

Install

• npm install better-auth-sync npm
• yarn add better-auth-sync yarn
• pnpm add better-auth-sync pnpm

Imports

• syncPlugin
  wrong:

  const syncPlugin = require('better-auth-sync').syncPlugin;

  correct:

  import { syncPlugin } from 'better-auth-sync';

  Primary plugin for Better Auth to enable webhook syncing.
• convexJwt
  wrong:

  import { convexJwt } from 'better-auth-sync';

  correct:

  import { convexJwt } from 'better-auth-sync/jwt';

  Imported from a subpath, specifically for Convex JWT integration. Ensure correct subpath import.
• authTables
  wrong:

  import { authTables } from 'better-auth-sync/schema';

  correct:

  import { authTables } from 'better-auth-sync/convex';

  Helper object for defining mirrored auth tables in Convex schema, imported from the `/convex` subpath.
• createConvexBetterAuth
  wrong:

  import { createConvexBetterAuth } from 'better-auth-sync';

  correct:

  import { createConvexBetterAuth } from 'better-auth-sync/react';

  React hook creator for integrating Convex auth context, specific to the `/react` subpath.

Quickstart

This code snippet demonstrates how to configure Better Auth with the `better-auth-sync` plugin and `convexJwt` for JWT integration, highlighting essential environment variables for a secure setup.

import { betterAuth } from "better-auth";
import { syncPlugin } from "better-auth-sync";
import { convexJwt } from "better-auth-sync/jwt";

// Ensure these environment variables are set in your Better Auth server environment
// BETTER_AUTH_URL=https://auth.your-app.com
// WEBHOOK_URL=https://your-project.convex.site/auth-webhook
// WEBHOOK_SECRET=replace-with-a-long-random-secret
// APP_ORIGIN=https://your-app.com

export const auth = betterAuth({
  // Replace with your actual adapter, trusted origins, and providers
  // adapter: ..., 
  // trustedOrigins: [process.env.APP_ORIGIN!],
  // providers: { email: { ... } },
  plugins: [
    convexJwt({
      issuer: process.env.APP_ORIGIN ?? 'https://your-app.com',
      audience: process.env.APP_ORIGIN ?? 'https://your-app.com'
    }),
    syncPlugin({
      secret: process.env.WEBHOOK_SECRET ?? 'your-webhook-secret-placeholder',
      url: process.env.WEBHOOK_URL ?? 'https://your-project.convex.site/auth-webhook',
      retryAttempts: 3
    })
  ]
});

console.log('Better Auth instance configured with sync and Convex JWT plugins.');
console.log('Ensure environment variables are correctly loaded and JWT issuer/audience match APP_ORIGIN.');