API keys and webhooks

pnpm --filter @workspace/auth add @better-auth/api-key@1.6.22

pnpm --filter @workspace/auth db:generate
pnpm with-env turbo db:generate
pnpm with-env pnpm --filter @workspace/db db:migrate

curl -H "x-api-key: YOUR_KEY" http://localhost:3000/api/organizations

const session = await auth.api.getSession({
  headers: new Headers({ "x-api-key": apiKey }),
});

import { relations } from "drizzle-orm";
import {
  boolean,
  integer,
  jsonb,
  pgEnum,
  pgTable,
  text,
  timestamp,
} from "drizzle-orm/pg-core";

import { generateId } from "@workspace/shared/utils";

import { createInsertSchema, createSelectSchema } from "../lib/zod";

import { organization, user } from "./auth";

export const webhookDeliveryStatusEnum = pgEnum("webhook_delivery_status", [
  "pending",
  "delivered",
  "failed",
]);

export const webhookEndpoint = pgTable("webhook_endpoint", {
  id: text().primaryKey().$defaultFn(generateId),
  organizationId: text().references(() => organization.id, {
    onDelete: "cascade",
  }),
  userId: text()
    .references(() => user.id, { onDelete: "cascade" })
    .notNull(),
  url: text().notNull(),
  secretHash: text().notNull(),
  events: jsonb().$type<string[]>().notNull(),
  enabled: boolean().notNull().default(true),
  createdAt: timestamp().notNull().defaultNow(),
  updatedAt: timestamp()
    .notNull()
    .$onUpdate(() => new Date()),
});

export const webhookDelivery = pgTable("webhook_delivery", {
  id: text().primaryKey().$defaultFn(generateId),
  endpointId: text()
    .references(() => webhookEndpoint.id, { onDelete: "cascade" })
    .notNull(),
  eventType: text().notNull(),
  payload: jsonb().notNull(),
  status: webhookDeliveryStatusEnum().notNull().default("pending"),
  attempts: integer().notNull().default(0),
  responseCode: integer(),
  createdAt: timestamp().notNull().defaultNow(),
  updatedAt: timestamp()
    .notNull()
    .$onUpdate(() => new Date()),
});

export const webhookEndpointRelations = relations(
  webhookEndpoint,
  ({ many }) => ({
    deliveries: many(webhookDelivery),
  }),
);

export const insertWebhookEndpointSchema = createInsertSchema(webhookEndpoint);
export const selectWebhookEndpointSchema = createSelectSchema(webhookEndpoint);

packages/webhooks/
  package.json          # name: @workspace/webhooks
  src/
    events.ts           # Zod payloads + event type union
    sign.ts             # HMAC sign / verify
    emit.ts             # look up endpoints, enqueue deliveries
    deliver.ts          # POST + retries
    index.ts

import * as z from "zod";

export const webhookEventTypes = [
  "user.created",
  "organization.member.joined",
  "organization.member.removed",
  "billing.subscription.updated",
  "billing.subscription.canceled",
  "webhook.ping",
] as const;

export const webhookEnvelopeSchema = z.object({
  id: z.string(),
  type: z.enum(webhookEventTypes),
  apiVersion: z.literal("2026-06-28"),
  createdAt: z.string().datetime(),
  data: z.record(z.string(), z.unknown()),
});

export type WebhookEnvelope = z.infer<typeof webhookEnvelopeSchema>;

const encoder = new TextEncoder();

export const signPayload = async (secret: string, body: string, t: number) => {
  const key = await crypto.subtle.importKey(
    "raw",
    encoder.encode(secret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"],
  );
  const mac = await crypto.subtle.sign(
    "HMAC",
    key,
    encoder.encode(`${t}.${body}`),
  );
  const v1 = [...new Uint8Array(mac)]
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
  return `t=${t},v1=${v1}`;
};

export const verifySignature = async (
  secret: string,
  body: string,
  header: string,
  toleranceSec = 300,
) => {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.trim().split("=")),
  );
  const t = Number(parts.t);
  if (!t || !parts.v1) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false;

  const expected = await signPayload(secret, body, t);
  const expectedV1 = expected.split("v1=")[1]!;
  return timingSafeEqual(expectedV1, parts.v1);
};

const timingSafeEqual = (a: string, b: string) => {
  if (a.length !== b.length) return false;
  let result = 0;
  for (let i = 0; i < a.length; i++) {
    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
  }
  return result === 0;
};

import { and, eq, sql } from "@workspace/db";
import { webhookDelivery, webhookEndpoint } from "@workspace/db/schema";
import { db } from "@workspace/db/server";
import { generateId } from "@workspace/shared/utils";

import { deliverWebhook } from "./deliver";

import type { WebhookEnvelope } from "./events";

export const emitWebhookEvent = async (input: {
  type: WebhookEnvelope["type"];
  data: Record<string, unknown>;
  organizationId?: string;
  userId?: string;
}) => {
  const envelope: WebhookEnvelope = {
    id: generateId(),
    type: input.type,
    apiVersion: "2026-06-28",
    createdAt: new Date().toISOString(),
    data: input.data,
  };

  const endpoints = await db
    .select()
    .from(webhookEndpoint)
    .where(
      and(
        eq(webhookEndpoint.enabled, true),
        input.organizationId
          ? eq(webhookEndpoint.organizationId, input.organizationId)
          : input.userId
            ? eq(webhookEndpoint.userId, input.userId)
            : sql`false`,
      ),
    );

  const matching = endpoints.filter((endpoint) =>
    endpoint.events.includes(input.type),
  );

  for (const endpoint of matching) {
    const [row] = await db
      .insert(webhookDelivery)
      .values({
        endpointId: endpoint.id,
        eventType: input.type,
        payload: envelope,
        status: "pending",
      })
      .returning();

    if (row) {
      void deliverWebhook(row.id);
    }
  }
};

import { emitWebhookEvent } from "@workspace/webhooks";

export const create = {
  before: async (user) => {
    /* existing name normalization */
  },
  after: async (user) => {
    await emitWebhookEvent({
      type: "user.created",
      userId: user.id,
      data: { id: user.id, email: user.email, name: user.name },
    });
  },
};

afterAcceptInvitation: async ({ organization, member }) => {
  await syncSubscriptionSeats(organization.id);
  await emitWebhookEvent({
    type: "organization.member.joined",
    organizationId: organization.id,
    data: {
      organizationId: organization.id,
      userId: member.userId,
      role: member.role,
    },
  });
},

export const upsertSubscription = async (data: InsertSubscription) => {
  const rows = await db
    .insert(subscription)
    .values(data)
    .onConflictDoUpdate({
      /* existing conflict target */
    })
    .returning();

  const row = rows[0];
  if (row) {
    await emitWebhookEvent({
      type:
        row.status === "canceled"
          ? "billing.subscription.canceled"
          : "billing.subscription.updated",
      data: {
        id: row.id,
        status: row.status,
        variantId: row.variantId,
        customerId: row.customerId,
      },
    });
  }

  return rows;
};