Skip to content

Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.

✨ 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.json
index 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.tsx
index 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>
<Trans
i18nKey="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.tsx
index 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.tsx
index 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>
<Trans
i18nKey="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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.json
index 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.sql
new file mode 100644
index 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.sql
new file mode 100644
index 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.prisma
index 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 migrations
events 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 history
cursor DateTime @default(now())