Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.
TypeScript i18nextnext-authnextjspostgresqlprismareact-emailt3-stacktailwindcsstrpcturborepotypescriptzod
✨ Make webhooks ready to flip: minute cron and per-endpoint version (#3339)
Luke Vellafdf3d004905e
diff --git a/apps/web/public/locales/en/app.json b/apps/web/public/locales/en/app.jsonindex ea946e3da..7747fd00a 100644--- a/apps/web/public/locales/en/app.json+++ b/apps/web/public/locales/en/app.json@@ -56,6 +56,7 @@"apiAccessBenefitDescription": "Create polls and read results from your own systems","apiAccessUpgradeDescription": "Create API keys to manage your polls programmatically. Included with Pro, with a shared limit of {count} requests per minute across your space.","apiAccessUpgradeTitle": "Upgrade for API access",+ "apiBetaNotice": "The API is in beta. Endpoints and responses may still change, and more will be added.","apiDailyLimitLabel": "Daily limit","apiDailyLimitValue": "{count, number} requests / day","apiKeyCreated": "API key created",@@ -94,6 +95,7 @@"banUserTitle": "Ban user","basicPolls": "Basic polls","basicPollsDescription": "Create simple scheduling polls",+ "beta": "Beta","billing": "Billing","billingDescription": "Manage your billing information and subscription.","billingSettings": "Billing settings",@@ -1000,6 +1002,7 @@"webhookLastDeliverySucceeded": "Delivered {date}","webhookLimitReached": "You've reached the maximum number of webhooks. Delete one before adding another.","webhooks": "Webhooks",+ "webhooksBetaNotice": "Webhooks are in beta. Events and payloads may still change, and more events will be added.","webhooksDescription": "Send events to your own server","webhookSecretSecurityWarning": "Store this secret securely. Use it to verify that deliveries came from Rallly.","webhooksSettingsDescription": "Send events to your own server with signed, retried deliveries.",diff --git a/apps/web/src/app/[locale]/(space)/settings/api-keys/page.tsx b/apps/web/src/app/[locale]/(space)/settings/api-keys/page.tsxindex 4d82554c2..9d3206b0f 100644--- a/apps/web/src/app/[locale]/(space)/settings/api-keys/page.tsx+++ b/apps/web/src/app/[locale]/(space)/settings/api-keys/page.tsx@@ -1,3 +1,6 @@+import { Alert, AlertDescription } from "@rallly/ui/alert";+import { Badge } from "@rallly/ui/badge";+import { FlaskConicalIcon } from "lucide-react";import type { Metadata } from "next";import { notFound } from "next/navigation";import {@@ -38,9 +41,16 @@ export default async function ApiKeysSettingsPage() {return (<SettingsPage><SettingsPageHeader>- <SettingsPageTitle>- <Trans i18nKey="apiKeys" defaults="API keys" />- </SettingsPageTitle>+ {/* Beside the heading, not inside it: Badge renders a div, which is+ not phrasing content an h1 may contain. */}+ <div className="flex items-center gap-2">+ <SettingsPageTitle>+ <Trans i18nKey="apiKeys" defaults="API keys" />+ </SettingsPageTitle>+ <Badge variant="amber" size="sm">+ <Trans i18nKey="beta" defaults="Beta" />+ </Badge>+ </div><SettingsPageDescription><Transi18nKey="apiKeysDescription"@@ -54,6 +64,15 @@ export default async function ApiKeysSettingsPage() {) : null}</SettingsPageHeader><SettingsPageContent>+ <Alert variant="warning">+ <FlaskConicalIcon />+ <AlertDescription>+ <Trans+ i18nKey="apiBetaNotice"+ defaults="The API is in beta. Endpoints and responses may still change, and more will be added."+ />+ </AlertDescription>+ </Alert>{enabled ? <ApiKeysContent /> : <ApiAccessUpgrade />}</SettingsPageContent></SettingsPage>diff --git a/apps/web/src/app/[locale]/(space)/settings/components/sidebar.tsx b/apps/web/src/app/[locale]/(space)/settings/components/sidebar.tsxindex 25bb6bb2b..6d7db25ba 100644--- a/apps/web/src/app/[locale]/(space)/settings/components/sidebar.tsx+++ b/apps/web/src/app/[locale]/(space)/settings/components/sidebar.tsx@@ -27,7 +27,6 @@ import {import { usePathname } from "next/navigation";import type React from "react";import { HoverPrefetchLink } from "@/components/hover-prefetch-link";-import { ProBadge } from "@/features/billing/components/pro-badge";import { useSpace } from "@/features/space/client";import { useAuthedUser } from "@/features/user/client";import { Trans, useTranslation } from "@/i18n/client";@@ -194,8 +193,7 @@ export function DeveloperSidebarMenu() {const isWebhooksEnabled = useFeatureFlag("webhooks");// Owner only: a member has no self-serve path to the developer surface. A- // free space sees the entries with a Pro badge; each page offers the- // upgrade.+ // free space still sees the entries; each page offers the upgrade.if (!isSpaceOwner || !isApiEnabled) {return null;}@@ -219,7 +217,6 @@ export function DeveloperSidebarMenu() {><KeyIcon /><Trans i18nKey="apiKeys" defaults="API keys" />- {space.tier !== "pro" ? <ProBadge className="ml-auto" /> : null}</SidebarMenuButton></SidebarMenuItem>{isWebhooksEnabled ? (@@ -235,7 +232,6 @@ export function DeveloperSidebarMenu() {><WebhookIcon /><Trans i18nKey="webhooks" defaults="Webhooks" />- {space.tier !== "pro" ? <ProBadge className="ml-auto" /> : null}</SidebarMenuButton></SidebarMenuItem>) : null}diff --git a/apps/web/src/app/[locale]/(space)/settings/webhooks/page.tsx b/apps/web/src/app/[locale]/(space)/settings/webhooks/page.tsxindex 66eab63d6..56614f1c3 100644--- a/apps/web/src/app/[locale]/(space)/settings/webhooks/page.tsx+++ b/apps/web/src/app/[locale]/(space)/settings/webhooks/page.tsx@@ -1,3 +1,6 @@+import { Alert, AlertDescription } from "@rallly/ui/alert";+import { Badge } from "@rallly/ui/badge";+import { FlaskConicalIcon } from "lucide-react";import type { Metadata } from "next";import { notFound } from "next/navigation";import {@@ -38,9 +41,16 @@ export default async function WebhooksSettingsPage() {return (<SettingsPage><SettingsPageHeader>- <SettingsPageTitle>- <Trans i18nKey="webhooks" defaults="Webhooks" />- </SettingsPageTitle>+ {/* Beside the heading, not inside it: Badge renders a div, which is+ not phrasing content an h1 may contain. */}+ <div className="flex items-center gap-2">+ <SettingsPageTitle>+ <Trans i18nKey="webhooks" defaults="Webhooks" />+ </SettingsPageTitle>+ <Badge variant="amber" size="sm">+ <Trans i18nKey="beta" defaults="Beta" />+ </Badge>+ </div><SettingsPageDescription><Transi18nKey="webhooksDescription"@@ -54,6 +64,15 @@ export default async function WebhooksSettingsPage() {) : null}</SettingsPageHeader><SettingsPageContent>+ <Alert variant="warning">+ <FlaskConicalIcon />+ <AlertDescription>+ <Trans+ i18nKey="webhooksBetaNotice"+ defaults="Webhooks are in beta. Events and payloads may still change, and more events will be added."+ />+ </AlertDescription>+ </Alert>{enabled ? <WebhooksContent /> : <WebhooksUpgrade />}</SettingsPageContent></SettingsPage>diff --git a/apps/web/src/features/webhook/constants.ts b/apps/web/src/features/webhook/constants.tsindex 6b8f34358..dcc4b1435 100644--- a/apps/web/src/features/webhook/constants.ts+++ b/apps/web/src/features/webhook/constants.ts@@ -77,10 +77,10 @@ export const getWebhookDocsPath = () =>* A change that could break a receiver (a renamed or removed field, a* changed shape) requires pinning to land first, in the same change:*- * 1. nullable `version` on SpaceWebhook, defaulted to this constant at- * creation and backfilled to the value below for existing rows — safe- * because every endpoint created before that migration was, by- * definition, built against it;+ * 1. (done) `version` on SpaceWebhook, written from this constant at+ * creation; rows that predate the column were backfilled to+ * 2026-09-20, which is what every endpoint before it was built+ * against;* 2. `buildWebhookPayload` takes the endpoint's version and branches, so* existing endpoints keep the shape they were written for while new* ones default to the new version;diff --git a/apps/web/src/features/webhook/data.ts b/apps/web/src/features/webhook/data.tsindex 54090778c..da68be781 100644--- a/apps/web/src/features/webhook/data.ts+++ b/apps/web/src/features/webhook/data.ts@@ -76,7 +76,13 @@ export function countSpaceWebhooks({ spaceId }: { spaceId: string }) {export async function listEnabledWebhooks() {return prisma.spaceWebhook.findMany({where: { enabled: true },- select: { id: true, spaceId: true, events: true, cursor: true },+ select: {+ id: true,+ spaceId: true,+ events: true,+ cursor: true,+ space: { select: { tier: true } },+ },orderBy: { createdAt: "asc" },});}diff --git a/apps/web/src/features/webhook/mutations.ts b/apps/web/src/features/webhook/mutations.tsindex 9d6551c0c..77ed3fbb3 100644--- a/apps/web/src/features/webhook/mutations.ts+++ b/apps/web/src/features/webhook/mutations.ts@@ -7,6 +7,7 @@ import { prisma } from "@rallly/database";import { decrypt, encrypt } from "@rallly/utils/encryption";import { Clock, Data, Effect } from "effect";import { env } from "@/env";+import { resolveSpaceTier } from "@/features/billing/utils";import type { DatabaseError } from "@/lib/effect/db";import { fromPrisma } from "@/lib/effect/db";import { AppError } from "@/lib/errors/app-error";@@ -20,6 +21,7 @@ import {IN_FLIGHT_TIMEOUT_MS,MAX_CONSECUTIVE_FAILURES,MAX_DELIVERY_ATTEMPTS,+ WEBHOOK_VERSION,} from "./constants";import {listDueDeliveryIds,@@ -45,6 +47,12 @@ import {* and never get past a window larger than what it reads. Each page commits* with its cursor, so a crash resumes from the last page, not the start.* Returns the number of deliveries created.+ *+ * Webhooks are a Pro capability, checked here the way the API checks it on+ * every request: an endpoint whose space is no longer Pro fans out nothing,+ * and its cursor still advances so an upgrade resumes from then rather than+ * replaying the gap. As with re-enabling an endpoint, the overlap window+ * behind the cursor can still deliver events from the last few minutes.*/export const fanOutWebhookEvents = Effect.fn("webhook.fanOutWebhookEvents")(function* ({ now }: { now: Date }) {@@ -56,6 +64,16 @@ export const fanOutWebhookEvents = Effect.fn("webhook.fanOutWebhookEvents")(continue;}+ if (resolveSpaceTier(webhook.space.tier) !== "pro") {+ yield* fromPrisma(() =>+ prisma.spaceWebhook.update({+ where: { id: webhook.id },+ data: { cursor: until },+ }),+ );+ continue;+ }+let after: { createdAt: Date; id?: string } = {createdAt: new Date(webhook.cursor.getTime() - FAN_OUT_OVERLAP_MS),};@@ -456,6 +474,9 @@ export async function createWebhook({url,events,secret: encrypt(secret, env.SECRET_PASSWORD),+ // Recorded here, not by the DB default, so a version bump in the+ // constant is what new endpoints get.+ version: WEBHOOK_VERSION,},select: { id: true },});diff --git a/apps/web/tests/webhooks-settings.spec.ts b/apps/web/tests/webhooks-settings.spec.tsindex 52001f3ae..1ccd0f3ba 100644--- a/apps/web/tests/webhooks-settings.spec.ts+++ b/apps/web/tests/webhooks-settings.spec.ts@@ -2,6 +2,7 @@ import type { Page } from "@playwright/test";import { expect, test } from "@playwright/test";import { prisma } from "@rallly/database";import { decrypt, encrypt } from "@rallly/utils/encryption";+import { WEBHOOK_VERSION } from "@/features/webhook/constants";import { WEBHOOK_EVENT_TYPES } from "@/features/webhook/schema";import {createUserInDb,@@ -56,6 +57,7 @@ async function createWebhookInDb({url,secret: encrypt("whsec_settings_test", SECRET_PASSWORD),events: ["poll.closed", "poll.reopened", "poll.scheduled"],+ version: WEBHOOK_VERSION,},});}@@ -114,6 +116,9 @@ test.describe("Webhooks settings", () => {});expect(webhook.url).toBe(url);expect(webhook.enabled).toBe(true);+ // Pinned at creation, so a later version bump cannot move an endpoint+ // that was built against this one.+ expect(webhook.version).toBe(WEBHOOK_VERSION);// The form starts with every event selected.expect([...webhook.events].sort()).toEqual([...WEBHOOK_EVENT_TYPES].sort());expect(decryptSecret(webhook.secret)).toBe(revealed);diff --git a/apps/web/tests/webhooks.spec.ts b/apps/web/tests/webhooks.spec.tsindex 3f5533e36..92bce7e7c 100644--- a/apps/web/tests/webhooks.spec.ts+++ b/apps/web/tests/webhooks.spec.ts@@ -8,7 +8,7 @@ import { prisma } from "@rallly/database";import { encrypt } from "@rallly/utils/encryption";import { WEBHOOK_VERSION } from "@/features/webhook/constants";import { WEBHOOK_EVENT_TYPES } from "@/features/webhook/schema";-import { createUserInDb } from "./test-utils";+import { createUserInDb, upgradeSpaceToPro } from "./test-utils";/*** Drives the webhook dispatcher cron against a local receiver: fan-out from@@ -85,14 +85,17 @@ test.describe("Webhook delivery", () => {return data.summary as Record<string, number>;}- async function createWebhook(overrides: { events?: string[] } = {}) {+ async function createWebhook(+ overrides: { events?: string[]; cursor?: Date } = {},+ ) {return prisma.spaceWebhook.create({data: {spaceId,url: receiver.url,secret: encrypt(WEBHOOK_SECRET, SECRET_PASSWORD),events: overrides.events ?? [...WEBHOOK_EVENT_TYPES],- cursor: secondsAgo(120),+ cursor: overrides.cursor ?? secondsAgo(120),+ version: WEBHOOK_VERSION,},});}@@ -129,6 +132,7 @@ test.describe("Webhook delivery", () => {where: { ownerId: owner.id },});spaceId = space.id;+ await upgradeSpaceToPro({ spaceId, userId: owner.id, seats: 1 });const poll = await prisma.poll.create({data: {id: "webhook-delivery-poll",@@ -147,6 +151,10 @@ test.describe("Webhook delivery", () => {receiver.status = 200;await prisma.spaceWebhook.deleteMany({ where: { spaceId } });await prisma.pollActivity.deleteMany({ where: { pollId } });+ await prisma.space.update({+ where: { id: spaceId },+ data: { tier: "pro" },+ });await prisma.poll.update({where: { id: pollId },data: { status: "open", deleted: false, deletedAt: null },@@ -223,6 +231,41 @@ test.describe("Webhook delivery", () => {expect(receiver.requests).toHaveLength(1);});+ test("stops delivering when the space is no longer Pro, without replaying the gap on upgrade", async ({+ request,+ }) => {+ // The event sits after the cursor but further back than the overlap+ // window, so once the cursor has moved past it nothing re-reads it.+ const webhook = await createWebhook({ cursor: secondsAgo(600) });+ await prisma.space.update({+ where: { id: spaceId },+ data: { tier: "hobby" },+ });+ await createActivity({+ type: "poll_closed",+ payload: { reason: "manual" },+ createdAt: secondsAgo(400),+ });++ const summary = await runCron(request);+ expect(summary.fannedOut).toBe(0);+ expect(receiver.requests).toHaveLength(0);++ // The cursor moved past the event, so upgrading later resumes from now.+ const paused = await prisma.spaceWebhook.findUniqueOrThrow({+ where: { id: webhook.id },+ });+ expect(paused.cursor.getTime()).toBeGreaterThan(Date.now() - 20_000);++ await prisma.space.update({+ where: { id: spaceId },+ data: { tier: "pro" },+ });+ const again = await runCron(request);+ expect(again.fannedOut).toBe(0);+ expect(receiver.requests).toHaveLength(0);+ });+test("delivers only subscribed events and skips disabled endpoints", async ({request,}) => {diff --git a/apps/web/vercel.json b/apps/web/vercel.jsonindex b3084249e..43447c569 100644--- a/apps/web/vercel.json+++ b/apps/web/vercel.json@@ -26,6 +26,10 @@{"path": "/api/house-keeping/delete-orphaned-anonymous-users","schedule": "45 * * * *"+ },+ {+ "path": "/api/house-keeping/deliver-webhooks",+ "schedule": "* * * * *"}]}diff --git a/packages/database/prisma/migrations/20260921120000_add_space_webhook_version/migration.sql b/packages/database/prisma/migrations/20260921120000_add_space_webhook_version/migration.sqlnew file mode 100644index 000000000..b536128e0--- /dev/null+++ b/packages/database/prisma/migrations/20260921120000_add_space_webhook_version/migration.sql@@ -0,0 +1,7 @@+-- Pin each webhook endpoint to the payload contract it was built against.+-- Every endpoint that exists before this column was, by definition, built+-- against 2026-09-20, so the default is a correct backfill. New rows get the+-- value written by the app.++-- AlterTable+ALTER TABLE "space_webhooks" ADD COLUMN "version" TEXT NOT NULL DEFAULT '2026-09-20';diff --git a/packages/database/prisma/migrations/20260922120000_drop_space_webhook_version_default/migration.sql b/packages/database/prisma/migrations/20260922120000_drop_space_webhook_version_default/migration.sqlnew file mode 100644index 000000000..75b9e46b9--- /dev/null+++ b/packages/database/prisma/migrations/20260922120000_drop_space_webhook_version_default/migration.sql@@ -0,0 +1,6 @@+-- The default existed only to backfill rows that predate the column. With+-- the backfill done, a writer that forgets the version must fail rather than+-- silently record a stale contract when WEBHOOK_VERSION moves.++-- AlterTable+ALTER TABLE "space_webhooks" ALTER COLUMN "version" DROP DEFAULT;diff --git a/packages/database/prisma/models/space.prisma b/packages/database/prisma/models/space.prismaindex 01b702df7..3595d1da3 100644--- a/packages/database/prisma/models/space.prisma+++ b/packages/database/prisma/models/space.prisma@@ -131,6 +131,8 @@ model SpaceWebhook {/// Subscribed event names (`poll.closed`, ...); validated by the feature schema, not a DB enum, so the vocabulary grows without migrationsevents String[]enabled Boolean @default(true)+ /// The payload contract this endpoint was built against (WEBHOOK_VERSION at creation). No default: a writer that forgets it fails instead of recording a stale contract. A breaking payload change branches on this so existing endpoints keep their shape+ version String/// Fan-out position in the poll activity log: activities created after this instant are still to be delivered. Starts at creation so a new endpoint never replays historycursor DateTime @default(now())