Skip to content

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

✨ Deliver signed, retried poll webhooks from the activity log (#3297)

Luke Vella536f7e2252dc
diff --git a/apps/web/.env.test b/apps/web/.env.test
index b92753ba3..c1e7953e4 100644
--- a/apps/web/.env.test
+++ b/apps/web/.env.test
@@ -16,3 +16,4 @@ SMTP_HOST=0.0.0.0
SMTP_PORT=1025
SMTP_REJECT_UNAUTHORIZED=false
+WEBHOOK_ALLOW_PRIVATE_URLS=true
diff --git a/apps/web/src/app/api/house-keeping/[...method]/route.ts b/apps/web/src/app/api/house-keeping/[...method]/route.ts
index 89b0cbde8..6a68e6822 100644
--- a/apps/web/src/app/api/house-keeping/[...method]/route.ts
+++ b/apps/web/src/app/api/house-keeping/[...method]/route.ts
@@ -17,6 +17,7 @@ import {
deleteOrphanedAnonymousUsers,
hardDeleteUser,
} from "@/features/user/mutations";
+import { deliverWebhooks } from "@/features/webhook/mutations";
import {
deletePostHogPerson,
flushPostHog,
@@ -204,4 +205,19 @@ app.get("/delete-orphaned-anonymous-users", async (c) => {
});
});
+app.get("/deliver-webhooks", async (c) => {
+ const summary = await deliverWebhooks();
+
+ // Runs every minute and most runs find nothing; log only when there was
+ // work so the signal isn't buried in 1,440 no-op lines a day.
+ if (summary.fannedOut > 0 || summary.attempted > 0 || summary.reclaimed > 0) {
+ logger.info(
+ { task: "deliver-webhooks", ...summary },
+ "Dispatched webhook deliveries",
+ );
+ }
+
+ return c.json({ success: true, summary });
+});
+
export const GET = handle(app);
diff --git a/apps/web/src/app/api/v1/schemas.ts b/apps/web/src/app/api/v1/schemas.ts
index d9faaa04d..734880d71 100644
--- a/apps/web/src/app/api/v1/schemas.ts
+++ b/apps/web/src/app/api/v1/schemas.ts
@@ -3,6 +3,16 @@ import { MAX_POLL_TITLE_LENGTH } from "@/features/poll/schema";
import { MAX_SLOT_GENERATION_DAYS } from "@/lib/datetime/slot-generator";
import { timezoneSchema } from "@/lib/utils/timezone-schema";
+// Webhook event payloads are documented alongside the API, but the feature
+// owns them: the dispatcher builds exactly these shapes.
+export {
+ pollClosedEventSchema,
+ pollReopenedEventSchema,
+ pollScheduledEventSchema,
+ webhookEventSchema,
+ webhookEventTypeSchema,
+} from "@/features/webhook/schema";
+
export const dateSchema = z.iso.date().meta({
description: "Date in YYYY-MM-DD format",
example: "2027-03-01",
diff --git a/apps/web/src/features/webhook/constants.ts b/apps/web/src/features/webhook/constants.ts
new file mode 100644
index 000000000..b5f7004a2
--- /dev/null
+++ b/apps/web/src/features/webhook/constants.ts
@@ -0,0 +1,45 @@
+/**
+ * Retry schedule indexed by the number of attempts already made: after the
+ * first failure wait 1 minute, after the second 5 minutes, and so on. A
+ * failure past the end of the schedule exhausts the delivery.
+ */
+export const RETRY_DELAYS_MS = [
+ 60_000,
+ 5 * 60_000,
+ 30 * 60_000,
+ 2 * 60 * 60_000,
+ 12 * 60 * 60_000,
+] as const;
+
+export const MAX_DELIVERY_ATTEMPTS = RETRY_DELAYS_MS.length + 1;
+
+/**
+ * Fan-out reads activities up to now minus this lag. cuid ids are not
+ * monotonic, so the cursor is `createdAt`, which is the start of the
+ * transaction that wrote the row, not its commit. The lag keeps the common
+ * case from ever seeing an uncommitted row.
+ */
+export const FAN_OUT_LAG_MS = 10_000;
+
+/**
+ * Each run re-reads this much history behind the cursor. A transaction that
+ * held its row open longer than the lag commits with a `createdAt` the
+ * cursor already passed; the overlap picks it up on a later run and the
+ * unique (webhook, activity) key drops the rows already fanned out. Far
+ * longer than any transaction timeout we configure (30s).
+ */
+export const FAN_OUT_OVERLAP_MS = 5 * 60_000;
+
+export const FAN_OUT_BATCH_SIZE = 500;
+
+export const DELIVERY_CLAIM_BATCH_SIZE = 100;
+
+export const DELIVERY_CONCURRENCY = 10;
+
+export const DELIVERY_TIMEOUT_MS = 10_000;
+
+/** An in-flight delivery older than this was orphaned by a crashed run. */
+export const IN_FLIGHT_TIMEOUT_MS = 2 * 60_000;
+
+/** Exhausted deliveries in a row before the endpoint is disabled. */
+export const MAX_CONSECUTIVE_FAILURES = 20;
diff --git a/apps/web/src/features/webhook/data.ts b/apps/web/src/features/webhook/data.ts
new file mode 100644
index 000000000..a52345105
--- /dev/null
+++ b/apps/web/src/features/webhook/data.ts
@@ -0,0 +1,85 @@
+import "server-only";
+
+import { prisma } from "@rallly/database";
+import { WEBHOOK_ACTIVITY_TYPES } from "./utils";
+
+/**
+ * System-context reads for the dispatcher cron. Scope here is proven by the
+ * webhook row itself — its spaceId was authorized when the endpoint was
+ * created — not by a session, so these take plain ids.
+ */
+
+export async function listEnabledWebhooks() {
+ return prisma.spaceWebhook.findMany({
+ where: { enabled: true },
+ select: { id: true, spaceId: true, events: true, cursor: true },
+ orderBy: { createdAt: "asc" },
+ });
+}
+
+/**
+ * Status transition activities in a space's polls after the `(createdAt, id)`
+ * keyset and up to `until`, oldest first. Keyset rather than offset so a run
+ * of equal timestamps larger than one page still advances. Deleted polls are
+ * excluded: their links no longer resolve and the poll is on its way out.
+ */
+export async function listWebhookActivities({
+ spaceId,
+ after,
+ until,
+ limit,
+}: {
+ spaceId: string;
+ after: { createdAt: Date; id?: string };
+ until: Date;
+ limit: number;
+}) {
+ return prisma.pollActivity.findMany({
+ where: {
+ type: { in: WEBHOOK_ACTIVITY_TYPES },
+ createdAt: { lte: until },
+ OR: after.id
+ ? [
+ { createdAt: { gt: after.createdAt } },
+ { createdAt: after.createdAt, id: { gt: after.id } },
+ ]
+ : [{ createdAt: { gt: after.createdAt } }],
+ poll: { spaceId, deleted: false },
+ },
+ select: {
+ id: true,
+ type: true,
+ optionId: true,
+ payload: true,
+ createdAt: true,
+ poll: { select: { id: true, title: true, kind: true, timeZone: true } },
+ },
+ orderBy: [{ createdAt: "asc" }, { id: "asc" }],
+ take: limit,
+ });
+}
+
+/**
+ * Deliveries due for an attempt on an enabled endpoint, oldest due first.
+ * Candidates only: the caller claims each one and may lose the race to a
+ * concurrent run.
+ */
+export async function listDueDeliveryIds({
+ now,
+ limit,
+}: {
+ now: Date;
+ limit: number;
+}) {
+ const rows = await prisma.webhookDelivery.findMany({
+ where: {
+ status: { in: ["pending", "failed"] },
+ nextAttemptAt: { lte: now },
+ webhook: { enabled: true },
+ },
+ select: { id: true },
+ orderBy: { nextAttemptAt: "asc" },
+ take: limit,
+ });
+ return rows.map((row) => row.id);
+}
diff --git a/apps/web/src/features/webhook/mutations.ts b/apps/web/src/features/webhook/mutations.ts
new file mode 100644
index 000000000..09cda667b
--- /dev/null
+++ b/apps/web/src/features/webhook/mutations.ts
@@ -0,0 +1,352 @@
+import "server-only";
+
+import type { Prisma } from "@rallly/database";
+import { prisma } from "@rallly/database";
+import { decrypt } from "@rallly/utils/encryption";
+import { env } from "@/env";
+import {
+ DELIVERY_CLAIM_BATCH_SIZE,
+ DELIVERY_CONCURRENCY,
+ FAN_OUT_BATCH_SIZE,
+ FAN_OUT_LAG_MS,
+ FAN_OUT_OVERLAP_MS,
+ IN_FLIGHT_TIMEOUT_MS,
+ MAX_CONSECUTIVE_FAILURES,
+ MAX_DELIVERY_ATTEMPTS,
+} from "./constants";
+import {
+ listDueDeliveryIds,
+ listEnabledWebhooks,
+ listWebhookActivities,
+} from "./data";
+import type { WebhookEventType } from "./schema";
+import type { WebhookSendResult } from "./service";
+import { sendWebhook } from "./service";
+import {
+ buildWebhookPayload,
+ getRetryDelayMs,
+ toWebhookEventType,
+} from "./utils";
+
+/**
+ * Turns new activity into delivery rows, one per (webhook, activity). The
+ * unique constraint makes re-reading harmless, so every run re-reads an
+ * overlap window behind the cursor and the cursor only advances to the lag
+ * boundary once a webhook's backlog is drained. Within a run, pages follow a
+ * `(createdAt, id)` keyset until the backlog is drained: the persisted cursor
+ * is a timestamp, so a run that stopped early would restart at the overlap
+ * 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.
+ */
+export async function fanOutWebhookEvents({ now }: { now: Date }) {
+ const until = new Date(now.getTime() - FAN_OUT_LAG_MS);
+ let created = 0;
+
+ for (const webhook of await listEnabledWebhooks()) {
+ if (webhook.cursor >= until) {
+ continue;
+ }
+
+ let after: { createdAt: Date; id?: string } = {
+ createdAt: new Date(webhook.cursor.getTime() - FAN_OUT_OVERLAP_MS),
+ };
+
+ for (;;) {
+ const activities = await listWebhookActivities({
+ spaceId: webhook.spaceId,
+ after,
+ until,
+ limit: FAN_OUT_BATCH_SIZE,
+ });
+
+ const deliveries = activities.flatMap((activity) => {
+ const eventType = toWebhookEventType(activity.type);
+ if (!eventType || !webhook.events.includes(eventType)) {
+ return [];
+ }
+ const payload = buildWebhookPayload({ activity, poll: activity.poll });
+ return payload
+ ? [
+ {
+ webhookId: webhook.id,
+ activityId: activity.id,
+ eventType,
+ payload: payload as unknown as Prisma.InputJsonObject,
+ // The run's own clock, not the database default: the claim
+ // that follows in the same run compares against this instant.
+ nextAttemptAt: now,
+ },
+ ]
+ : [];
+ });
+
+ const last = activities.at(-1);
+ const drained = activities.length < FAN_OUT_BATCH_SIZE || !last;
+ // A partial page means the boundary was reached; a full one stops at
+ // its last row, and the overlap covers anything that lands behind it.
+ const cursor = drained ? until : last.createdAt;
+
+ const [result] = await prisma.$transaction([
+ prisma.webhookDelivery.createMany({
+ data: deliveries,
+ skipDuplicates: true,
+ }),
+ prisma.spaceWebhook.update({
+ where: { id: webhook.id },
+ data: { cursor },
+ }),
+ ]);
+ created += result.count;
+
+ if (drained) {
+ break;
+ }
+ after = { createdAt: last.createdAt, id: last.id };
+ }
+ }
+
+ return created;
+}
+
+/**
+ * Returns in-flight deliveries abandoned by a run that died mid-send to the
+ * queue. The attempt was already counted at claim time, so a delivery that
+ * keeps dying still exhausts instead of looping forever.
+ */
+export async function reclaimStaleDeliveries({ now }: { now: Date }) {
+ const staleBefore = new Date(now.getTime() - IN_FLIGHT_TIMEOUT_MS);
+ const [exhausted, reclaimed] = await prisma.$transaction([
+ prisma.webhookDelivery.updateMany({
+ where: {
+ status: "in_flight",
+ updatedAt: { lt: staleBefore },
+ attempts: { gte: MAX_DELIVERY_ATTEMPTS },
+ },
+ data: { status: "exhausted", lastError: "Delivery run did not finish" },
+ }),
+ prisma.webhookDelivery.updateMany({
+ where: { status: "in_flight", updatedAt: { lt: staleBefore } },
+ data: { status: "pending" },
+ }),
+ ]);
+ return exhausted.count + reclaimed.count;
+}
+
+/**
+ * Claims due deliveries for this run. Each claim is a conditional update on
+ * one row, so two overlapping runs never send the same delivery: whichever
+ * flips it to in_flight owns it. Counting the attempt here rather than on
+ * completion means a run that dies after sending still used an attempt.
+ */
+export async function claimDueDeliveries({
+ now,
+ limit,
+}: {
+ now: Date;
+ limit: number;
+}) {
+ const claimed: string[] = [];
+ for (const id of await listDueDeliveryIds({ now, limit })) {
+ const { count } = await prisma.webhookDelivery.updateMany({
+ where: {
+ id,
+ status: { in: ["pending", "failed"] },
+ nextAttemptAt: { lte: now },
+ // Re-checked here, not only when listing candidates: another run
+ // may have disabled the endpoint in between.
+ webhook: { enabled: true },
+ },
+ data: { status: "in_flight", attempts: { increment: 1 } },
+ });
+ if (count === 1) {
+ claimed.push(id);
+ }
+ }
+
+ return prisma.webhookDelivery.findMany({
+ where: { id: { in: claimed } },
+ select: {
+ id: true,
+ eventType: true,
+ payload: true,
+ attempts: true,
+ webhook: { select: { id: true, url: true, secret: true } },
+ },
+ });
+}
+
+export type DeliveryOutcome = "succeeded" | "failed" | "exhausted" | "disabled";
+
+/**
+ * Records an attempt's outcome on the delivery and its endpoint. A failure
+ * with schedule left is re-queued with backoff; past the schedule it is
+ * exhausted and counts against the endpoint, which is disabled once too
+ * many exhaust in a row. Any success resets that count.
+ */
+export async function recordDeliveryResult({
+ deliveryId,
+ webhookId,
+ attempts,
+ result,
+ now,
+}: {
+ deliveryId: string;
+ webhookId: string;
+ attempts: number;
+ result: WebhookSendResult;
+ now: Date;
+}): Promise<DeliveryOutcome> {
+ return prisma.$transaction(async (tx) => {
+ if (result.ok) {
+ await tx.webhookDelivery.update({
+ where: { id: deliveryId },
+ data: {
+ status: "succeeded",
+ lastResponseStatus: result.status,
+ lastError: null,
+ },
+ });
+ await tx.spaceWebhook.update({
+ where: { id: webhookId },
+ data: { lastDeliveredAt: now, consecutiveFailures: 0 },
+ });
+ return "succeeded";
+ }
+
+ const delay = getRetryDelayMs(attempts);
+ if (delay !== null) {
+ await tx.webhookDelivery.update({
+ where: { id: deliveryId },
+ data: {
+ status: "failed",
+ nextAttemptAt: new Date(now.getTime() + delay),
+ lastResponseStatus: result.status,
+ lastError: result.error,
+ },
+ });
+ await tx.spaceWebhook.update({
+ where: { id: webhookId },
+ data: { lastFailedAt: now },
+ });
+ return "failed";
+ }
+
+ await tx.webhookDelivery.update({
+ where: { id: deliveryId },
+ data: {
+ status: "exhausted",
+ lastResponseStatus: result.status,
+ lastError: result.error,
+ },
+ });
+ const webhook = await tx.spaceWebhook.update({
+ where: { id: webhookId },
+ data: { lastFailedAt: now, consecutiveFailures: { increment: 1 } },
+ select: { enabled: true, consecutiveFailures: true },
+ });
+ if (
+ webhook.enabled &&
+ webhook.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES
+ ) {
+ await tx.spaceWebhook.update({
+ where: { id: webhookId },
+ data: { enabled: false },
+ });
+ return "disabled";
+ }
+ return "exhausted";
+ });
+}
+
+/**
+ * Every failure mode ends in a result: a delivery is already in flight by
+ * now, and a throw here would leave it stranded until stale reclamation.
+ */
+async function attemptDelivery(delivery: {
+ id: string;
+ eventType: string;
+ payload: Prisma.JsonValue;
+ webhook: { url: string; secret: string };
+}): Promise<WebhookSendResult> {
+ let secret: string;
+ try {
+ secret = decrypt(delivery.webhook.secret, env.SECRET_PASSWORD);
+ } catch {
+ return {
+ ok: false,
+ status: null,
+ error: "Could not decrypt the endpoint secret",
+ };
+ }
+ return sendWebhook({
+ url: delivery.webhook.url,
+ secret,
+ deliveryId: delivery.id,
+ eventType: delivery.eventType as WebhookEventType,
+ body: JSON.stringify(delivery.payload),
+ });
+}
+
+export type DeliverWebhooksSummary = {
+ reclaimed: number;
+ fannedOut: number;
+ attempted: number;
+ succeeded: number;
+ failed: number;
+ exhausted: number;
+ disabled: number;
+};
+
+/**
+ * One dispatcher run: recover orphans, fan out new activity, then send what
+ * is due. Sends run a few at a time so a slow endpoint cannot hold the whole
+ * batch to its timeout, and every outcome is recorded before the run ends.
+ */
+export async function deliverWebhooks({
+ now = new Date(),
+}: {
+ now?: Date;
+} = {}): Promise<DeliverWebhooksSummary> {
+ const summary: DeliverWebhooksSummary = {
+ reclaimed: 0,
+ fannedOut: 0,
+ attempted: 0,
+ succeeded: 0,
+ failed: 0,
+ exhausted: 0,
+ disabled: 0,
+ };
+
+ summary.reclaimed = await reclaimStaleDeliveries({ now });
+ summary.fannedOut = await fanOutWebhookEvents({ now });
+
+ const deliveries = await claimDueDeliveries({
+ now,
+ limit: DELIVERY_CLAIM_BATCH_SIZE,
+ });
+ summary.attempted = deliveries.length;
+
+ for (let i = 0; i < deliveries.length; i += DELIVERY_CONCURRENCY) {
+ const outcomes = await Promise.all(
+ deliveries.slice(i, i + DELIVERY_CONCURRENCY).map(async (delivery) => {
+ const result = await attemptDelivery(delivery);
+ return recordDeliveryResult({
+ deliveryId: delivery.id,
+ webhookId: delivery.webhook.id,
+ attempts: delivery.attempts,
+ result,
+ now: new Date(),
+ });
+ }),
+ );
+ for (const outcome of outcomes) {
+ if (outcome === "disabled") {
+ summary.exhausted++;
+ }
+ summary[outcome]++;
+ }
+ }
+
+ return summary;
+}
diff --git a/apps/web/src/features/webhook/schema.test.ts b/apps/web/src/features/webhook/schema.test.ts
new file mode 100644
index 000000000..ea1073418
--- /dev/null
+++ b/apps/web/src/features/webhook/schema.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { webhookUrlSchema } from "./schema";
+
+describe("webhookUrlSchema", () => {
+ it.each([
+ "https://example.com/hooks/rallly",
+ "https://hooks.example.com:8443/path?x=1",
+ "https://172.32.0.1/hook",
+ ])("accepts %s", (url) => {
+ expect(webhookUrlSchema.safeParse(url).success).toBe(true);
+ });
+
+ it.each([
+ ["not a url", "not-a-url"],
+ ["http", "http://example.com/hook"],
+ ["ftp", "ftp://example.com/hook"],
+ ["localhost", "https://localhost/hook"],
+ ["localhost subdomain", "https://app.localhost/hook"],
+ ["loopback", "https://127.0.0.1/hook"],
+ ["ipv6 loopback", "https://[::1]/hook"],
+ ["rfc1918 10/8", "https://10.1.2.3/hook"],
+ ["rfc1918 172.16/12", "https://172.20.0.1/hook"],
+ ["rfc1918 192.168/16", "https://192.168.0.10/hook"],
+ ["link-local", "https://169.254.169.254/latest/meta-data"],
+ ["ipv4-mapped", "https://[::ffff:10.0.0.1]/hook"],
+ ["credentials", "https://user:[email protected]/hook"],
+ ])("rejects %s", (_label, url) => {
+ expect(webhookUrlSchema.safeParse(url).success).toBe(false);
+ });
+});
diff --git a/apps/web/src/features/webhook/schema.ts b/apps/web/src/features/webhook/schema.ts
new file mode 100644
index 000000000..8686ed8ff
--- /dev/null
+++ b/apps/web/src/features/webhook/schema.ts
@@ -0,0 +1,142 @@
+import * as z from "zod";
+import { pollClosedReasonSchema } from "@/features/poll/schema";
+import { getWebhookUrlRejection } from "./utils";
+
+export const webhookEventTypeSchema = z
+ .enum(["poll.closed", "poll.reopened", "poll.scheduled"])
+ .meta({
+ id: "WebhookEventType",
+ description: "The poll lifecycle transition the event records.",
+ example: "poll.closed",
+ });
+
+export type WebhookEventType = z.infer<typeof webhookEventTypeSchema>;
+
+export const WEBHOOK_EVENT_TYPES = webhookEventTypeSchema.options;
+
+const webhookPollSchema = (status: "open" | "closed" | "scheduled") =>
+ z
+ .object({
+ id: z.string().meta({ example: "Xk3pQ9vLm2Ab" }),
+ title: z.string().meta({ example: "Team sync" }),
+ status: z.literal(status).meta({
+ description:
+ "The status the transition moved the poll to. Reflects this event, not the poll's current state: a later transition arrives as its own event.",
+ }),
+ kind: z.enum(["date", "time"]).meta({ example: "time" }),
+ timeZone: z.string().nullable().meta({ example: "Europe/London" }),
+ adminUrl: z
+ .string()
+ .meta({ example: "https://app.rallly.co/poll/Xk3pQ9vLm2Ab" }),
+ inviteUrl: z
+ .string()
+ .meta({ example: "https://rallly.co/invite/Xk3pQ9vLm2Ab" }),
+ })
+ .meta({ id: `WebhookPoll${status[0]?.toUpperCase()}${status.slice(1)}` });
+
+const envelope = {
+ id: z.string().meta({
+ description:
+ "Stable event id. Retries of the same event carry the same id, so receivers can deduplicate on it.",
+ example: "cm5h8x2k40000q9l4f7e2d3an",
+ }),
+ createdAt: z.iso.datetime().meta({
+ description: "When the transition happened.",
+ example: "2025-01-12T08:30:00.000Z",
+ }),
+};
+
+export const pollClosedEventSchema = z
+ .object({
+ ...envelope,
+ type: z.literal("poll.closed"),
+ data: z.object({
+ poll: webhookPollSchema("closed"),
+ reason: pollClosedReasonSchema.meta({
+ description:
+ "`manual` when the organizer closed the poll, `auto` when it closed because every option had passed.",
+ }),
+ }),
+ })
+ .meta({ id: "PollClosedEvent" });
+
+export const pollReopenedEventSchema = z
+ .object({
+ ...envelope,
+ type: z.literal("poll.reopened"),
+ data: z.object({ poll: webhookPollSchema("open") }),
+ })
+ .meta({ id: "PollReopenedEvent" });
+
+export const pollScheduledEventSchema = z
+ .object({
+ ...envelope,
+ type: z.literal("poll.scheduled"),
+ data: z.object({
+ poll: webhookPollSchema("scheduled"),
+ option: z
+ .union([
+ z.object({
+ id: z.string().meta({ example: "cm5h8x2k40000q9l4f7e2d3an" }),
+ date: z.iso.date().meta({ example: "2025-01-15" }),
+ }),
+ z.object({
+ id: z.string().meta({ example: "cm5h8x2k40000q9l4f7e2d3an" }),
+ startTime: z.iso
+ .datetime()
+ .meta({ example: "2025-01-15T09:00:00.000Z" }),
+ duration: z.int().positive().meta({ example: 30 }),
+ }),
+ ])
+ .meta({
+ description:
+ "The option the poll was scheduled on. Its shape follows the poll's `kind`: a date for `date` polls, a start time and duration for `time` polls.",
+ }),
+ }),
+ })
+ .meta({ id: "PollScheduledEvent" });
+
+export const webhookEventSchema = z
+ .discriminatedUnion("type", [
+ pollClosedEventSchema,
+ pollReopenedEventSchema,
+ pollScheduledEventSchema,
+ ])
+ .meta({ id: "WebhookEvent" });
+
+export type WebhookEvent = z.infer<typeof webhookEventSchema>;
+
+const rejectionMessages = {
+ invalid: "Enter a valid URL",
+ insecure_scheme: "Webhook URLs must use https",
+ credentials: "Webhook URLs must not contain credentials",
+ private_host: "Webhook URLs must point at a public host",
+} as const;
+
+export const webhookUrlSchema = z
+ .url({ protocol: /^https$/ })
+ .max(2048)
+ .superRefine((value, ctx) => {
+ const rejection = URL.canParse(value)
+ ? getWebhookUrlRejection(new URL(value))
+ : "invalid";
+ if (rejection) {
+ ctx.addIssue({ code: "custom", message: rejectionMessages[rejection] });
+ }
+ });
+
+export const createWebhookInputSchema = z.object({
+ url: webhookUrlSchema,
+ events: z.array(webhookEventTypeSchema).min(1),
+});
+
+export type CreateWebhookInput = z.infer<typeof createWebhookInputSchema>;
+
+export const updateWebhookInputSchema = z.object({
+ webhookId: z.string(),
+ url: webhookUrlSchema.optional(),
+ events: z.array(webhookEventTypeSchema).min(1).optional(),
+ enabled: z.boolean().optional(),
+});
+
+export type UpdateWebhookInput = z.infer<typeof updateWebhookInputSchema>;
diff --git a/apps/web/src/features/webhook/service.test.ts b/apps/web/src/features/webhook/service.test.ts
new file mode 100644
index 000000000..36a10353f
--- /dev/null
+++ b/apps/web/src/features/webhook/service.test.ts
@@ -0,0 +1,82 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { guardedLookup, PrivateAddressError, sendWebhook } from "./service";
+
+function lookupResult(hostname: string, all: boolean) {
+ return new Promise<{ err: Error | null; address: unknown }>((resolve) => {
+ guardedLookup(hostname, { all }, (err, address) =>
+ resolve({ err, address }),
+ );
+ });
+}
+
+describe("guardedLookup", () => {
+ it("refuses a name that resolves to loopback", async () => {
+ const { err } = await lookupResult("localhost", false);
+ expect(err).toBeInstanceOf(PrivateAddressError);
+ });
+
+ it("refuses a private IP literal", async () => {
+ const { err } = await lookupResult("10.0.0.1", true);
+ expect(err).toBeInstanceOf(PrivateAddressError);
+ });
+
+ it("hands back a public literal in the shape the caller asked for", async () => {
+ const single = await lookupResult("8.8.8.8", false);
+ expect(single.err).toBeNull();
+ expect(single.address).toBe("8.8.8.8");
+
+ const all = await lookupResult("8.8.8.8", true);
+ expect(all.err).toBeNull();
+ expect(all.address).toEqual([{ address: "8.8.8.8", family: 4 }]);
+ });
+});
+
+describe("sendWebhook", () => {
+ const PROXY_VARS = ["HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"];
+ let originalEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ originalEnv = Object.fromEntries(
+ [...PROXY_VARS, "WEBHOOK_ALLOW_PRIVATE_URLS"].map((name) => [
+ name,
+ process.env[name],
+ ]),
+ );
+ for (const name of PROXY_VARS) {
+ delete process.env[name];
+ }
+ delete process.env.WEBHOOK_ALLOW_PRIVATE_URLS;
+ });
+
+ afterEach(() => {
+ for (const [name, value] of Object.entries(originalEnv)) {
+ if (value === undefined) {
+ delete process.env[name];
+ } else {
+ process.env[name] = value;
+ }
+ }
+ });
+
+ // Loopback is always exempt from the proxy, so with a proxy configured
+ // this request takes the direct path — the one that must carry the
+ // guarded lookup. Resolution fails before any socket opens, so the test
+ // needs neither a proxy nor a listener.
+ it("refuses a hostname that resolves to a private address on the direct path behind a proxy", async () => {
+ process.env.HTTPS_PROXY = "http://proxy.invalid:3128";
+
+ const result = await sendWebhook({
+ url: "https://localhost/hook",
+ secret: "whsec_test",
+ deliveryId: "d_1",
+ eventType: "poll.closed",
+ body: "{}",
+ });
+
+ expect(result).toEqual({
+ ok: false,
+ status: null,
+ error: "Webhook host resolves to a private address",
+ });
+ });
+});
diff --git a/apps/web/src/features/webhook/service.ts b/apps/web/src/features/webhook/service.ts
new file mode 100644
index 000000000..fcf5df5fd
--- /dev/null
+++ b/apps/web/src/features/webhook/service.ts
@@ -0,0 +1,176 @@
+import "server-only";
+
+import type { LookupAddress, LookupOptions } from "node:dns";
+import { lookup } from "node:dns";
+import { isIP } from "node:net";
+import type { Dispatcher } from "undici";
+import { getGlobalDispatcher } from "undici";
+import { createOutboundDispatcher } from "@/lib/outbound-proxy";
+import { DELIVERY_TIMEOUT_MS } from "./constants";
+import { isPrivateAddress, signWebhookBody } from "./utils";
+
+export type WebhookSendResult =
+ | { ok: true; status: number }
+ | { ok: false; status: number | null; error: string };
+
+/**
+ * Local development and the integration suite point endpoints at loopback,
+ * which the sender otherwise refuses. Never set in production.
+ */
+function allowsPrivateTargets() {
+ return process.env.WEBHOOK_ALLOW_PRIVATE_URLS === "true";
+}
+
+export class PrivateAddressError extends Error {
+ constructor() {
+ super("Webhook host resolves to a private address");
+ this.name = "PrivateAddressError";
+ }
+}
+
+/**
+ * A `net.connect` lookup that refuses private addresses. Installed on the
+ * connection itself so the address that passes the check is the address the
+ * socket connects to: a separate pre-check would leave a window for DNS
+ * rebinding between the check and the connect.
+ */
+export function guardedLookup(
+ hostname: string,
+ options: LookupOptions,
+ callback: (
+ err: NodeJS.ErrnoException | null,
+ address: string | LookupAddress[],
+ family?: number,
+ ) => void,
+) {
+ lookup(hostname, { ...options, all: true }, (err, addresses) => {
+ if (err) {
+ return callback(err, []);
+ }
+ if (addresses.some((entry) => isPrivateAddress(entry.address))) {
+ return callback(new PrivateAddressError(), []);
+ }
+ if (options.all) {
+ return callback(null, addresses);
+ }
+ const [first] = addresses;
+ if (!first) {
+ return callback(
+ Object.assign(new Error(`getaddrinfo ENOTFOUND ${hostname}`), {
+ code: "ENOTFOUND",
+ }),
+ [],
+ );
+ }
+ callback(null, first.address, first.family);
+ });
+}
+
+let guardedDispatcher: Dispatcher | null = null;
+
+/**
+ * Direct connections pin the guarded lookup, including hosts that NO_PROXY
+ * exempts from a configured proxy. Proxied connections are made by the proxy,
+ * which resolves the hostname itself, so pinning is not possible there; the
+ * proxy operator controls what it can reach.
+ */
+function getDispatcher() {
+ if (allowsPrivateTargets()) {
+ return getGlobalDispatcher();
+ }
+ guardedDispatcher ??= createOutboundDispatcher({
+ connect: { lookup: guardedLookup },
+ });
+ return guardedDispatcher;
+}
+
+/**
+ * Cheap rejections before any connection is made. IP literals never go
+ * through a lookup, so they are the one case that must be judged here.
+ */
+function getTargetRejection(url: URL) {
+ if (allowsPrivateTargets()) {
+ return null;
+ }
+ if (url.protocol !== "https:") {
+ return "Webhook URL must use https";
+ }
+ const hostname = url.hostname.replace(/^\[|\]$/g, "");
+ if (isIP(hostname) && isPrivateAddress(hostname)) {
+ return "Webhook host is a private address";
+ }
+ return null;
+}
+
+/**
+ * POSTs one signed event to an endpoint. A 2xx response is a success;
+ * anything else — including redirects, which are never followed because
+ * the redirect target was not checked — is a failure the caller schedules a
+ * retry for. Never throws: the outcome is the return value.
+ */
+export async function sendWebhook({
+ url,
+ secret,
+ deliveryId,
+ eventType,
+ body,
+}: {
+ url: string;
+ secret: string;
+ deliveryId: string;
+ eventType: string;
+ body: string;
+}): Promise<WebhookSendResult> {
+ let target: URL;
+ try {
+ target = new URL(url);
+ } catch {
+ return { ok: false, status: null, error: "Invalid webhook URL" };
+ }
+
+ const rejection = getTargetRejection(target);
+ if (rejection) {
+ return { ok: false, status: null, error: rejection };
+ }
+
+ try {
+ const timestamp = Math.floor(Date.now() / 1000);
+ const signature = await signWebhookBody({ secret, body, timestamp });
+ const response = await fetch(target, {
+ method: "POST",
+ headers: {
+ "Content-Type": "application/json",
+ "User-Agent": "Rallly-Webhooks/1.0",
+ "X-Rallly-Event": eventType,
+ "X-Rallly-Delivery": deliveryId,
+ "X-Rallly-Signature": signature,
+ },
+ body,
+ redirect: "manual",
+ signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+ // Node extension, absent from the DOM RequestInit type.
+ ...({ dispatcher: getDispatcher() } as object),
+ });
+ // The body is irrelevant and untrusted: release the socket without
+ // buffering it.
+ await response.body?.cancel().catch(() => undefined);
+
+ if (response.ok) {
+ return { ok: true, status: response.status };
+ }
+ return {
+ ok: false,
+ status: response.status,
+ error: `HTTP ${response.status}`,
+ };
+ } catch (error) {
+ const message =
+ error instanceof Error
+ ? error.name === "TimeoutError"
+ ? `Timed out after ${DELIVERY_TIMEOUT_MS / 1000}s`
+ : (error.cause instanceof Error ? error.cause.message : null) ||
+ error.message
+ : "Request failed";
+ return { ok: false, status: null, error: message.slice(0, 500) };
+ }
+}
diff --git a/apps/web/src/features/webhook/utils.test.ts b/apps/web/src/features/webhook/utils.test.ts
new file mode 100644
index 000000000..82597f348
--- /dev/null
+++ b/apps/web/src/features/webhook/utils.test.ts
@@ -0,0 +1,230 @@
+import { createHmac } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import {
+ buildWebhookPayload,
+ getRetryDelayMs,
+ isPrivateAddress,
+ signWebhookBody,
+ toWebhookEventType,
+} from "./utils";
+
+describe("signWebhookBody", () => {
+ it("produces t=<unix>,v1=<hmac-sha256(secret, t.body)>", async () => {
+ const body = '{"hello":"world"}';
+ const secret = "whsec_test";
+ const timestamp = 1_700_000_000;
+
+ const expectedDigest = createHmac("sha256", secret)
+ .update(`${timestamp}.${body}`)
+ .digest("hex");
+
+ expect(await signWebhookBody({ secret, body, timestamp })).toBe(
+ `t=${timestamp},v1=${expectedDigest}`,
+ );
+ });
+
+ it("changes when the body changes", async () => {
+ const a = await signWebhookBody({ secret: "s", body: "a", timestamp: 1 });
+ const b = await signWebhookBody({ secret: "s", body: "b", timestamp: 1 });
+ expect(a).not.toBe(b);
+ });
+});
+
+describe("getRetryDelayMs", () => {
+ it("follows the 1m, 5m, 30m, 2h, 12h schedule by attempt number", () => {
+ expect(getRetryDelayMs(1)).toBe(60_000);
+ expect(getRetryDelayMs(2)).toBe(5 * 60_000);
+ expect(getRetryDelayMs(3)).toBe(30 * 60_000);
+ expect(getRetryDelayMs(4)).toBe(2 * 60 * 60_000);
+ expect(getRetryDelayMs(5)).toBe(12 * 60 * 60_000);
+ });
+
+ it("is exhausted after the sixth attempt", () => {
+ expect(getRetryDelayMs(6)).toBeNull();
+ expect(getRetryDelayMs(7)).toBeNull();
+ });
+});
+
+describe("toWebhookEventType", () => {
+ it("maps status transition activities to their event names", () => {
+ expect(toWebhookEventType("poll_closed")).toBe("poll.closed");
+ expect(toWebhookEventType("poll_reopened")).toBe("poll.reopened");
+ expect(toWebhookEventType("poll_scheduled")).toBe("poll.scheduled");
+ });
+
+ it("returns null for activities that are not webhook events", () => {
+ expect(toWebhookEventType("response_created")).toBeNull();
+ expect(toWebhookEventType("poll_created")).toBeNull();
+ });
+});
+
+describe("buildWebhookPayload", () => {
+ const poll = {
+ id: "Xk3pQ9vLm2Ab",
+ title: "Team sync",
+ kind: "time" as const,
+ timeZone: "Europe/London",
+ };
+ const createdAt = new Date("2026-09-15T10:00:00.000Z");
+
+ it("derives the status from the event, not the live poll", () => {
+ const payload = buildWebhookPayload({
+ activity: {
+ id: "act_1",
+ type: "poll_closed",
+ optionId: null,
+ payload: { reason: "manual" },
+ createdAt,
+ },
+ poll,
+ });
+
+ expect(payload).toMatchObject({
+ id: "act_1",
+ type: "poll.closed",
+ createdAt: "2026-09-15T10:00:00.000Z",
+ data: {
+ poll: {
+ id: "Xk3pQ9vLm2Ab",
+ title: "Team sync",
+ status: "closed",
+ kind: "time",
+ timeZone: "Europe/London",
+ },
+ reason: "manual",
+ },
+ });
+ expect(payload?.data.poll.adminUrl).toMatch(/\/poll\/Xk3pQ9vLm2Ab$/);
+ expect(payload?.data.poll.inviteUrl).toMatch(/\/invite\/Xk3pQ9vLm2Ab$/);
+ });
+
+ it("marks a reopened poll as open", () => {
+ const payload = buildWebhookPayload({
+ activity: {
+ id: "act_2",
+ type: "poll_reopened",
+ optionId: null,
+ payload: {},
+ createdAt,
+ },
+ poll,
+ });
+
+ expect(payload?.type).toBe("poll.reopened");
+ expect(payload?.data.poll.status).toBe("open");
+ });
+
+ it("carries the scheduled slot for a time poll", () => {
+ const payload = buildWebhookPayload({
+ activity: {
+ id: "act_3",
+ type: "poll_scheduled",
+ optionId: "opt_1",
+ payload: { start: "2026-10-01T09:00:00.000Z", duration: 30 },
+ createdAt,
+ },
+ poll,
+ });
+
+ expect(payload).toMatchObject({
+ type: "poll.scheduled",
+ data: {
+ poll: { status: "scheduled" },
+ option: {
+ id: "opt_1",
+ startTime: "2026-10-01T09:00:00.000Z",
+ duration: 30,
+ },
+ },
+ });
+ });
+
+ it("carries the scheduled date for a date poll", () => {
+ const payload = buildWebhookPayload({
+ activity: {
+ id: "act_4",
+ type: "poll_scheduled",
+ optionId: "opt_2",
+ payload: { start: "2026-10-01T00:00:00.000Z", duration: 0 },
+ createdAt,
+ },
+ poll: { ...poll, kind: "date" },
+ });
+
+ expect(payload?.data).toMatchObject({
+ option: { id: "opt_2", date: "2026-10-01" },
+ });
+ });
+
+ it("returns null for activities that are not webhook events", () => {
+ expect(
+ buildWebhookPayload({
+ activity: {
+ id: "act_5",
+ type: "response_created",
+ optionId: null,
+ payload: { name: "Jessie" },
+ createdAt,
+ },
+ poll,
+ }),
+ ).toBeNull();
+ });
+
+ it("returns null when the activity payload is malformed", () => {
+ expect(
+ buildWebhookPayload({
+ activity: {
+ id: "act_6",
+ type: "poll_scheduled",
+ optionId: "opt_1",
+ payload: {},
+ createdAt,
+ },
+ poll,
+ }),
+ ).toBeNull();
+ });
+});
+
+describe("isPrivateAddress", () => {
+ it.each([
+ "127.0.0.1",
+ "127.10.0.1",
+ "0.0.0.0",
+ "10.0.0.1",
+ "172.16.0.1",
+ "172.31.255.255",
+ "192.168.1.1",
+ "169.254.169.254",
+ "100.64.0.1",
+ "198.18.0.1",
+ "198.19.255.255",
+ "192.0.0.1",
+ "192.0.2.1",
+ "198.51.100.1",
+ "203.0.113.1",
+ "::1",
+ "::",
+ "fe80::1",
+ "fc00::1",
+ "fd12:3456::1",
+ "::ffff:127.0.0.1",
+ "::ffff:10.0.0.1",
+ "::ffff:c0a8:0101",
+ ])("rejects %s", (address) => {
+ expect(isPrivateAddress(address)).toBe(true);
+ });
+
+ it.each([
+ "8.8.8.8",
+ "1.1.1.1",
+ "172.32.0.1",
+ "198.20.0.1",
+ "198.52.100.1",
+ "2606:4700:4700::1111",
+ "::ffff:8.8.8.8",
+ ])("allows %s", (address) => {
+ expect(isPrivateAddress(address)).toBe(false);
+ });
+});
diff --git a/apps/web/src/features/webhook/utils.ts b/apps/web/src/features/webhook/utils.ts
new file mode 100644
index 000000000..65983d9a7
--- /dev/null
+++ b/apps/web/src/features/webhook/utils.ts
@@ -0,0 +1,284 @@
+import { absoluteUrl, shortUrl } from "@rallly/utils/absolute-url";
+import { pollActivitySchema } from "@/features/poll/activity/schema";
+import { RETRY_DELAYS_MS } from "./constants";
+import type { WebhookEvent, WebhookEventType } from "./schema";
+
+/**
+ * Stripe-style signature: `t=<unix seconds>,v1=<hex hmac-sha256>` over
+ * `${t}.${body}`. Including the timestamp in the signed string lets a
+ * receiver reject replays without the signature itself carrying state.
+ * Web Crypto rather than node:crypto keeps this module importable from
+ * schema.ts, which client forms validate with.
+ */
+export async function signWebhookBody({
+ secret,
+ body,
+ timestamp,
+}: {
+ secret: string;
+ body: string;
+ timestamp: number;
+}) {
+ const encoder = new TextEncoder();
+ const key = await crypto.subtle.importKey(
+ "raw",
+ encoder.encode(secret),
+ { name: "HMAC", hash: "SHA-256" },
+ false,
+ ["sign"],
+ );
+ const signature = await crypto.subtle.sign(
+ "HMAC",
+ key,
+ encoder.encode(`${timestamp}.${body}`),
+ );
+ const digest = Array.from(new Uint8Array(signature), (byte) =>
+ byte.toString(16).padStart(2, "0"),
+ ).join("");
+ return `t=${timestamp},v1=${digest}`;
+}
+
+/**
+ * Delay before the next attempt given how many attempts have been made, or
+ * null once the schedule is exhausted.
+ */
+export function getRetryDelayMs(attempts: number) {
+ return RETRY_DELAYS_MS[attempts - 1] ?? null;
+}
+
+const ACTIVITY_EVENTS: Record<string, WebhookEventType> = {
+ poll_closed: "poll.closed",
+ poll_reopened: "poll.reopened",
+ poll_scheduled: "poll.scheduled",
+};
+
+export const WEBHOOK_ACTIVITY_TYPES = Object.keys(ACTIVITY_EVENTS);
+
+export function toWebhookEventType(activityType: string) {
+ return ACTIVITY_EVENTS[activityType] ?? null;
+}
+
+// All-day options are stored as UTC midnight of the calendar date, so the
+// date is the first ten characters of the ISO string.
+function toOptionPayload(
+ kind: "date" | "time",
+ option: { id: string; start: string; duration: number },
+) {
+ if (kind === "date") {
+ return { id: option.id, date: option.start.slice(0, 10) };
+ }
+ return { id: option.id, startTime: option.start, duration: option.duration };
+}
+
+/**
+ * Builds the event envelope for an activity row. The poll's status comes from
+ * the transition the activity records, never from the live poll: by the time
+ * a delivery is retried the poll may have moved on, and each transition is
+ * its own event. Returns null for activities that are not webhook events or
+ * whose payload this version can't interpret.
+ */
+export function buildWebhookPayload({
+ activity,
+ poll,
+}: {
+ activity: {
+ id: string;
+ type: string;
+ optionId: string | null;
+ payload: unknown;
+ createdAt: Date;
+ };
+ poll: {
+ id: string;
+ title: string;
+ kind: "date" | "time";
+ timeZone: string | null;
+ };
+}): WebhookEvent | null {
+ const parsed = pollActivitySchema.safeParse({
+ type: activity.type,
+ userId: null,
+ optionId: activity.optionId ?? undefined,
+ payload: activity.payload,
+ });
+
+ if (!parsed.success) {
+ return null;
+ }
+
+ const event = parsed.data;
+ const base = {
+ id: activity.id,
+ createdAt: activity.createdAt.toISOString(),
+ };
+ const pollPayload = (status: "open" | "closed" | "scheduled") => ({
+ id: poll.id,
+ title: poll.title,
+ status,
+ kind: poll.kind,
+ timeZone: poll.timeZone,
+ adminUrl: absoluteUrl(`/poll/${poll.id}`),
+ inviteUrl: shortUrl(`/invite/${poll.id}`),
+ });
+
+ switch (event.type) {
+ case "poll_closed":
+ return {
+ ...base,
+ type: "poll.closed",
+ data: { poll: pollPayload("closed"), reason: event.payload.reason },
+ };
+ case "poll_reopened":
+ return {
+ ...base,
+ type: "poll.reopened",
+ data: { poll: pollPayload("open") },
+ };
+ case "poll_scheduled":
+ return {
+ ...base,
+ type: "poll.scheduled",
+ data: {
+ poll: pollPayload("scheduled"),
+ option: toOptionPayload(poll.kind, {
+ id: event.optionId,
+ start: event.payload.start,
+ duration: event.payload.duration,
+ }),
+ },
+ };
+ default:
+ return null;
+ }
+}
+
+function parseIPv4(address: string) {
+ const parts = address.split(".");
+ if (parts.length !== 4) {
+ return null;
+ }
+ const octets = parts.map((part) =>
+ /^\d{1,3}$/.test(part) ? Number(part) : Number.NaN,
+ );
+ return octets.every((octet) => octet <= 255) ? octets : null;
+}
+
+/**
+ * Every IPv4 range the IANA special-purpose registry marks as not globally
+ * reachable, so a webhook can never be pointed at anything a deployment's
+ * network might route internally.
+ */
+function isPrivateIPv4([a = 0, b = 0, c = 0]: number[]) {
+ return (
+ a === 0 || // "this" network, includes 0.0.0.0
+ a === 10 ||
+ a === 127 ||
+ (a === 100 && b >= 64 && b <= 127) || // carrier-grade NAT
+ (a === 169 && b === 254) ||
+ (a === 172 && b >= 16 && b <= 31) ||
+ (a === 192 && b === 0 && c === 0) || // IETF protocol assignments
+ (a === 192 && b === 0 && c === 2) || // TEST-NET-1
+ (a === 192 && b === 168) ||
+ (a === 198 && (b === 18 || b === 19)) || // benchmarking
+ (a === 198 && b === 51 && c === 100) || // TEST-NET-2
+ (a === 203 && b === 0 && c === 113) || // TEST-NET-3
+ a >= 224 // multicast and reserved, includes broadcast
+ );
+}
+
+/** Expands an IPv6 literal into eight 16-bit groups, or null if malformed. */
+function parseIPv6(address: string) {
+ let value = address;
+ // IPv4-mapped / compatible tail, e.g. ::ffff:10.0.0.1
+ const lastColon = value.lastIndexOf(":");
+ const tail = value.slice(lastColon + 1);
+ if (tail.includes(".")) {
+ const octets = parseIPv4(tail);
+ if (!octets) {
+ return null;
+ }
+ const [a, b, c, d] = octets;
+ value = `${value.slice(0, lastColon)}:${(((a as number) << 8) | (b as number)).toString(16)}:${(((c as number) << 8) | (d as number)).toString(16)}`;
+ }
+
+ const halves = value.split("::");
+ if (halves.length > 2) {
+ return null;
+ }
+ const toGroups = (part: string) =>
+ part === ""
+ ? []
+ : part.split(":").map((group) => Number.parseInt(group, 16));
+ const head = toGroups(halves[0] ?? "");
+ const tailGroups = halves.length === 2 ? toGroups(halves[1] ?? "") : [];
+ const missing = 8 - head.length - tailGroups.length;
+ if (missing < 0 || (halves.length === 1 && missing !== 0)) {
+ return null;
+ }
+ const groups = [...head, ...new Array(missing).fill(0), ...tailGroups];
+ return groups.every((group) => Number.isInteger(group) && group <= 0xffff)
+ ? groups
+ : null;
+}
+
+function isPrivateIPv6(groups: number[]) {
+ const [g0 = 0, g1 = 0, g2 = 0, g3 = 0, g4 = 0, g5 = 0, g6 = 0, g7 = 0] =
+ groups;
+ const leadingZero = g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0;
+ if (leadingZero && g5 === 0xffff) {
+ return isPrivateIPv4([g6 >> 8, g6 & 0xff, g7 >> 8, g7 & 0xff]);
+ }
+ if (leadingZero && g5 === 0 && g6 === 0 && g7 <= 1) {
+ return true; // unspecified (::) and loopback (::1)
+ }
+ return (
+ (g0 & 0xffc0) === 0xfe80 || // link-local
+ (g0 & 0xfe00) === 0xfc00 // unique local
+ );
+}
+
+/**
+ * Whether an IP literal points at a network a webhook must never reach:
+ * loopback, link-local (including the cloud metadata endpoint), RFC 1918 and
+ * their IPv6 counterparts. Pure so it can run in the browser for form
+ * validation as well as on the server after DNS resolution.
+ */
+export function isPrivateAddress(address: string) {
+ const ipv4 = parseIPv4(address);
+ if (ipv4) {
+ return isPrivateIPv4(ipv4);
+ }
+ const ipv6 = parseIPv6(address);
+ if (ipv6) {
+ return isPrivateIPv6(ipv6);
+ }
+ return false;
+}
+
+export type WebhookUrlRejection =
+ | "insecure_scheme"
+ | "credentials"
+ | "private_host";
+
+/**
+ * Why a parsed URL is not an acceptable webhook target, or null if it is.
+ * Only IP literals can be judged here; a hostname that resolves to a private
+ * address is caught by the sender after DNS resolution.
+ */
+export function getWebhookUrlRejection(url: URL): WebhookUrlRejection | null {
+ if (url.protocol !== "https:") {
+ return "insecure_scheme";
+ }
+ if (url.username || url.password) {
+ return "credentials";
+ }
+ const hostname = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+ if (
+ hostname === "localhost" ||
+ hostname.endsWith(".localhost") ||
+ isPrivateAddress(hostname)
+ ) {
+ return "private_host";
+ }
+ return null;
+}
diff --git a/apps/web/src/lib/outbound-proxy.test.ts b/apps/web/src/lib/outbound-proxy.test.ts
index 35a1a75f9..9593fc221 100644
--- a/apps/web/src/lib/outbound-proxy.test.ts
+++ b/apps/web/src/lib/outbound-proxy.test.ts
@@ -1,163 +1,38 @@
-import type { Server } from "node:http";
-import { createServer } from "node:http";
-import type { AddressInfo } from "node:net";
-import { getGlobalDispatcher, setGlobalDispatcher } from "undici";
-import { afterEach, beforeEach, expect, test, vi } from "vitest";
-import { setupOutboundProxy } from "./outbound-proxy";
+import { Agent, EnvHttpProxyAgent } from "undici";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createOutboundDispatcher } from "./outbound-proxy";
-vi.mock("@rallly/logger", () => ({
- createLogger: () => ({ info: vi.fn() }),
-}));
+const PROXY_VARS = ["HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"];
-const PROXY_ENV_VARS = [
- "HTTP_PROXY",
- "HTTPS_PROXY",
- "http_proxy",
- "https_proxy",
- "NO_PROXY",
- "no_proxy",
-];
+describe("createOutboundDispatcher", () => {
+ let originalProxyEnv: Record<string, string | undefined>;
-const savedEnv: Record<string, string | undefined> = {};
-const originalDispatcher = getGlobalDispatcher();
-const servers: Server[] = [];
-
-beforeEach(() => {
- for (const name of PROXY_ENV_VARS) {
- savedEnv[name] = process.env[name];
- delete process.env[name];
- }
-});
-
-afterEach(async () => {
- for (const name of PROXY_ENV_VARS) {
- if (savedEnv[name] === undefined) {
+ beforeEach(() => {
+ originalProxyEnv = Object.fromEntries(
+ PROXY_VARS.map((name) => [name, process.env[name]]),
+ );
+ for (const name of PROXY_VARS) {
delete process.env[name];
- } else {
- process.env[name] = savedEnv[name];
}
- }
- setGlobalDispatcher(originalDispatcher);
- await Promise.all(
- servers
- .splice(0)
- .map((server) => new Promise((resolve) => server.close(resolve))),
- );
-});
-
-function listen(server: Server, host = "127.0.0.1") {
- servers.push(server);
- return new Promise<number>((resolve) => {
- server.listen(0, host, () => {
- resolve((server.address() as AddressInfo).port);
- });
- });
-}
-
-/**
- * A local server that behaves as a forward proxy for both proxying styles:
- * CONNECT tunneling (what undici uses today) and absolute-form requests
- * (what curl uses for plain HTTP), so the test doesn't break if undici
- * changes mechanics across majors. Every request is answered with "proxied"
- * and the target host is recorded.
- */
-async function startProxyServer() {
- const targets: string[] = [];
-
- const proxy = createServer((req, res) => {
- targets.push(new URL(req.url as string).host);
- res.setHeader("connection", "close");
- res.end("proxied");
- });
-
- proxy.on("connect", (req, clientSocket) => {
- targets.push(req.url as string);
- clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
- clientSocket.once("data", () => {
- clientSocket.end(
- "HTTP/1.1 200 OK\r\ncontent-length: 7\r\nconnection: close\r\n\r\nproxied",
- );
- });
- clientSocket.on("error", () => {});
});
- return { port: await listen(proxy), targets };
-}
-
-async function startOriginServer(host: string) {
- const origin = createServer((_req, res) => {
- res.setHeader("connection", "close");
- res.end("direct");
+ afterEach(() => {
+ for (const name of PROXY_VARS) {
+ const value = originalProxyEnv[name];
+ if (value === undefined) {
+ delete process.env[name];
+ } else {
+ process.env[name] = value;
+ }
+ }
});
- return { port: await listen(origin, host) };
-}
-
-/**
- * The load-bearing assumption behind setupOutboundProxy is that the INSTALLED
- * undici package's setGlobalDispatcher registers the dispatcher that Node's
- * BUNDLED undici (global fetch) consults — they share a Symbol.for-registered
- * global. If a Node upgrade ships an undici whose global-dispatcher symbol
- * version no longer matches the installed package's, the proxy setup becomes
- * a silent no-op. The target host is unresolvable (.invalid), so this fetch
- * can only succeed by going through the proxy.
- */
-test("Node's global fetch routes through the proxy from HTTP_PROXY", async () => {
- const { port, targets } = await startProxyServer();
- process.env.HTTP_PROXY = `http://127.0.0.1:${port}`;
-
- setupOutboundProxy();
-
- const res = await fetch("http://rallly-proxy-contract-check.invalid/ping", {
- signal: AbortSignal.timeout(5000),
+ it("connects directly when no proxy is configured", () => {
+ expect(createOutboundDispatcher()).toBeInstanceOf(Agent);
});
- expect(res.status).toBe(200);
- expect(await res.text()).toBe("proxied");
- expect(targets).toContainEqual(
- expect.stringContaining("rallly-proxy-contract-check.invalid"),
- );
-});
-
-test.each([
- "localhost",
- "127.0.0.1",
-])("loopback host %s bypasses the proxy even without NO_PROXY", async (host) => {
- const { port: proxyPort, targets } = await startProxyServer();
- const { port: originPort } = await startOriginServer(host);
- process.env.HTTP_PROXY = `http://127.0.0.1:${proxyPort}`;
-
- setupOutboundProxy();
-
- const res = await fetch(`http://${host}:${originPort}/ping`, {
- signal: AbortSignal.timeout(5000),
+ it("routes through the environment proxy when one is configured", () => {
+ process.env.HTTPS_PROXY = "http://proxy.example.com:3128";
+ expect(createOutboundDispatcher()).toBeInstanceOf(EnvHttpProxyAgent);
});
-
- expect(await res.text()).toBe("direct");
- expect(targets).toEqual([]);
-});
-
-test("lowercase no_proxy entries are honored", async () => {
- const { port, targets } = await startProxyServer();
- process.env.http_proxy = `http://127.0.0.1:${port}`;
- process.env.no_proxy = "proxy-exempt.invalid";
-
- setupOutboundProxy();
-
- // Exempt from the proxy, the unresolvable host can only fail DNS — reaching
- // the proxy would have succeeded, which is what the last assertion rules out.
- await expect(
- fetch("http://proxy-exempt.invalid/ping", {
- signal: AbortSignal.timeout(5000),
- }),
- ).rejects.toThrow("fetch failed");
- expect(targets).toEqual([]);
-});
-
-test("leaves the global dispatcher untouched when no proxy variables are set", () => {
- const before = getGlobalDispatcher();
-
- setupOutboundProxy();
-
- expect(getGlobalDispatcher()).toBe(before);
});
diff --git a/apps/web/src/lib/outbound-proxy.ts b/apps/web/src/lib/outbound-proxy.ts
index 90edf471a..2020a28c9 100644
--- a/apps/web/src/lib/outbound-proxy.ts
+++ b/apps/web/src/lib/outbound-proxy.ts
@@ -1,7 +1,7 @@
import "server-only";
import { createLogger } from "@rallly/logger";
-import { EnvHttpProxyAgent, setGlobalDispatcher } from "undici";
+import { Agent, EnvHttpProxyAgent, setGlobalDispatcher } from "undici";
const logger = createLogger("outbound-proxy");
@@ -24,6 +24,11 @@ function sanitize(value: string) {
}
}
+/** Whether outbound fetches are routed through a proxy from the environment. */
+export function isOutboundProxyConfigured() {
+ return PROXY_ENV_VARS.some((name) => process.env[name]);
+}
+
/**
* Loopback traffic is never proxied, regardless of NO_PROXY: a CONNECT to
* "localhost" through a remote proxy reaches the proxy's loopback, never this
@@ -53,22 +58,36 @@ export function setupOutboundProxy() {
return;
}
- const noProxy = [
- process.env.no_proxy ?? process.env.NO_PROXY,
- LOOPBACK_NO_PROXY,
- ]
- .filter(Boolean)
- .join(",");
-
- setGlobalDispatcher(new EnvHttpProxyAgent({ noProxy }));
+ const dispatcher = createOutboundDispatcher();
+ setGlobalDispatcher(dispatcher);
logger.info(
{
proxies: Object.fromEntries(
configured.map((name) => [name, sanitize(process.env[name] as string)]),
),
- noProxy,
+ noProxy: getNoProxy(),
},
"Outbound proxy enabled: fetch will route through the configured proxy",
);
}
+
+function getNoProxy() {
+ return [process.env.no_proxy ?? process.env.NO_PROXY, LOOPBACK_NO_PROXY]
+ .filter(Boolean)
+ .join(",");
+}
+
+/**
+ * A dispatcher that follows the proxy environment the same way the global
+ * one does, so a caller that needs its own connection options (a pinned DNS
+ * lookup, say) keeps the proxy routing. `connect` options apply to direct
+ * connections only: proxied ones are made by the proxy, and hosts exempted
+ * by NO_PROXY come back through the direct path.
+ */
+export function createOutboundDispatcher(options: Agent.Options = {}) {
+ if (isOutboundProxyConfigured()) {
+ return new EnvHttpProxyAgent({ ...options, noProxy: getNoProxy() });
+ }
+ return new Agent(options);
+}
diff --git a/apps/web/tests/webhooks.spec.ts b/apps/web/tests/webhooks.spec.ts
new file mode 100644
index 000000000..3ec8aa0dc
--- /dev/null
+++ b/apps/web/tests/webhooks.spec.ts
@@ -0,0 +1,521 @@
+import { createHmac } from "node:crypto";
+import type { Server } from "node:http";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { APIRequestContext } from "@playwright/test";
+import { expect, test } from "@playwright/test";
+import { prisma } from "@rallly/database";
+import { encrypt } from "@rallly/utils/encryption";
+import { createUserInDb } from "./test-utils";
+
+/**
+ * Drives the webhook dispatcher cron against a local receiver: fan-out from
+ * the poll activity log, signed delivery, retry with backoff, exhaustion,
+ * cursor lag, reclaiming orphaned in-flight rows and disabling an endpoint
+ * that keeps failing. The receiver is loopback, which the sender normally
+ * refuses; .env.test sets WEBHOOK_ALLOW_PRIVATE_URLS for exactly this.
+ */
+
+const CRON_SECRET = process.env.CRON_SECRET;
+const SECRET_PASSWORD = process.env.SECRET_PASSWORD as string;
+const WEBHOOK_SECRET = "whsec_integration_test";
+
+type ReceivedRequest = {
+ headers: Record<string, string | string[] | undefined>;
+ body: string;
+};
+
+class Receiver {
+ readonly requests: ReceivedRequest[] = [];
+ status = 200;
+ private server: Server | null = null;
+ url = "";
+
+ async start() {
+ this.server = createServer((req, res) => {
+ let body = "";
+ req.on("data", (chunk) => {
+ body += chunk;
+ });
+ req.on("end", () => {
+ this.requests.push({ headers: req.headers, body });
+ res.statusCode = this.status;
+ res.end();
+ });
+ });
+ await new Promise<void>((resolve) =>
+ this.server?.listen(0, "127.0.0.1", resolve),
+ );
+ const { port } = this.server?.address() as AddressInfo;
+ this.url = `http://127.0.0.1:${port}/hook`;
+ }
+
+ async stop() {
+ await new Promise<void>((resolve) => this.server?.close(() => resolve()));
+ }
+}
+
+function secondsAgo(seconds: number) {
+ return new Date(Date.now() - seconds * 1000);
+}
+
+function verifySignature(header: string, body: string) {
+ const [t, v1] = header.split(",").map((part) => part.split("=")[1]);
+ const expected = createHmac("sha256", WEBHOOK_SECRET)
+ .update(`${t}.${body}`)
+ .digest("hex");
+ return v1 === expected;
+}
+
+test.describe("Webhook delivery", () => {
+ const receiver = new Receiver();
+ const createdUserIds: string[] = [];
+ let spaceId: string;
+ let pollId: string;
+
+ async function runCron(request: APIRequestContext) {
+ const response = await request.get("/api/house-keeping/deliver-webhooks", {
+ headers: { Authorization: `Bearer ${CRON_SECRET}` },
+ });
+ expect(response.ok()).toBeTruthy();
+ const data = await response.json();
+ expect(data.success).toBe(true);
+ return data.summary as Record<string, number>;
+ }
+
+ async function createWebhook(overrides: { events?: string[] } = {}) {
+ return prisma.spaceWebhook.create({
+ data: {
+ spaceId,
+ url: receiver.url,
+ secret: encrypt(WEBHOOK_SECRET, SECRET_PASSWORD),
+ events: overrides.events ?? [
+ "poll.closed",
+ "poll.reopened",
+ "poll.scheduled",
+ ],
+ cursor: secondsAgo(120),
+ },
+ });
+ }
+
+ async function createActivity({
+ type,
+ payload,
+ createdAt,
+ optionId,
+ }: {
+ type: string;
+ payload: object;
+ createdAt: Date;
+ optionId?: string;
+ }) {
+ return prisma.pollActivity.create({
+ data: { pollId, type, payload, createdAt, optionId },
+ });
+ }
+
+ test.beforeAll(async () => {
+ await receiver.start();
+ await prisma.user.deleteMany({
+ where: { email: { startsWith: "webhook-delivery-" } },
+ });
+ const owner = await createUserInDb({
+ name: "Webhook Owner",
+ email: "[email protected]",
+ });
+ createdUserIds.push(owner.id);
+ const space = await prisma.space.findFirstOrThrow({
+ where: { ownerId: owner.id },
+ });
+ spaceId = space.id;
+ const poll = await prisma.poll.create({
+ data: {
+ id: "webhook-delivery-poll",
+ title: "Webhook poll",
+ kind: "time",
+ timeZone: "Europe/London",
+ userId: owner.id,
+ spaceId,
+ },
+ });
+ pollId = poll.id;
+ });
+
+ test.beforeEach(async () => {
+ receiver.requests.length = 0;
+ receiver.status = 200;
+ await prisma.spaceWebhook.deleteMany({ where: { spaceId } });
+ await prisma.pollActivity.deleteMany({ where: { pollId } });
+ });
+
+ test.afterAll(async () => {
+ await prisma.user.deleteMany({ where: { id: { in: createdUserIds } } });
+ await receiver.stop();
+ });
+
+ test("fans out a closed poll into a signed delivery, once", async ({
+ request,
+ }) => {
+ const webhook = await createWebhook();
+ const activity = await createActivity({
+ type: "poll_closed",
+ payload: { reason: "manual" },
+ createdAt: secondsAgo(30),
+ });
+ // Not a webhook event: must not produce a delivery
+ await createActivity({
+ type: "response_created",
+ payload: { name: "Jessie" },
+ createdAt: secondsAgo(30),
+ });
+
+ const summary = await runCron(request);
+ expect(summary.fannedOut).toBe(1);
+ expect(summary.succeeded).toBe(1);
+
+ expect(receiver.requests).toHaveLength(1);
+ const [received] = receiver.requests;
+ expect(received?.headers["x-rallly-event"]).toBe("poll.closed");
+ expect(received?.headers["content-type"]).toBe("application/json");
+ const signature = received?.headers["x-rallly-signature"] as string;
+ expect(verifySignature(signature, received?.body ?? "")).toBe(true);
+
+ const body = JSON.parse(received?.body ?? "{}");
+ expect(body).toMatchObject({
+ id: activity.id,
+ type: "poll.closed",
+ createdAt: activity.createdAt.toISOString(),
+ data: {
+ poll: {
+ id: pollId,
+ title: "Webhook poll",
+ status: "closed",
+ kind: "time",
+ timeZone: "Europe/London",
+ },
+ reason: "manual",
+ },
+ });
+
+ const delivery = await prisma.webhookDelivery.findUniqueOrThrow({
+ where: {
+ webhookId_activityId: {
+ webhookId: webhook.id,
+ activityId: activity.id,
+ },
+ },
+ });
+ expect(received?.headers["x-rallly-delivery"]).toBe(delivery.id);
+ expect(delivery.status).toBe("succeeded");
+ expect(delivery.attempts).toBe(1);
+ expect(delivery.lastResponseStatus).toBe(200);
+
+ const updated = await prisma.spaceWebhook.findUniqueOrThrow({
+ where: { id: webhook.id },
+ });
+ expect(updated.lastDeliveredAt).not.toBeNull();
+ expect(updated.cursor.getTime()).toBeGreaterThan(
+ activity.createdAt.getTime(),
+ );
+
+ // A second run finds nothing new and sends nothing again
+ const again = await runCron(request);
+ expect(again.fannedOut).toBe(0);
+ expect(receiver.requests).toHaveLength(1);
+ });
+
+ test("delivers only subscribed events and skips disabled endpoints", async ({
+ request,
+ }) => {
+ const closedOnly = await createWebhook({ events: ["poll.closed"] });
+ const disabled = await createWebhook();
+ await prisma.spaceWebhook.update({
+ where: { id: disabled.id },
+ data: { enabled: false },
+ });
+ await createActivity({
+ type: "poll_reopened",
+ payload: {},
+ createdAt: secondsAgo(30),
+ });
+
+ const summary = await runCron(request);
+ expect(summary.fannedOut).toBe(0);
+ expect(receiver.requests).toHaveLength(0);
+ expect(
+ await prisma.webhookDelivery.count({
+ where: { webhookId: { in: [closedOnly.id, disabled.id] } },
+ }),
+ ).toBe(0);
+ });
+
+ test("carries the scheduled option for a scheduled poll", async ({
+ request,
+ }) => {
+ await createWebhook();
+ await createActivity({
+ type: "poll_scheduled",
+ optionId: "webhook-delivery-option",
+ payload: { start: "2026-10-01T09:00:00.000Z", duration: 30 },
+ createdAt: secondsAgo(30),
+ });
+
+ await runCron(request);
+
+ expect(receiver.requests).toHaveLength(1);
+ expect(JSON.parse(receiver.requests[0]?.body ?? "{}")).toMatchObject({
+ type: "poll.scheduled",
+ data: {
+ poll: { status: "scheduled" },
+ option: {
+ id: "webhook-delivery-option",
+ startTime: "2026-10-01T09:00:00.000Z",
+ duration: 30,
+ },
+ },
+ });
+ });
+
+ test("picks up an activity that committed behind the cursor", async ({
+ request,
+ }) => {
+ // Cursor is 120s back; a row whose transaction started earlier but
+ // committed late is inside the overlap window and must still fan out.
+ await createWebhook();
+ const late = await createActivity({
+ type: "poll_closed",
+ payload: { reason: "auto" },
+ createdAt: secondsAgo(200),
+ });
+
+ const summary = await runCron(request);
+ expect(summary.fannedOut).toBe(1);
+ expect(JSON.parse(receiver.requests[0]?.body ?? "{}").id).toBe(late.id);
+ });
+
+ test("advances through a backlog larger than one page at a single timestamp", async ({
+ request,
+ }) => {
+ // autoClosePolls records every closed poll in one transaction, so they
+ // share a createdAt; a page boundary inside that run must not stick.
+ const webhook = await createWebhook();
+ const createdAt = secondsAgo(60);
+ await prisma.pollActivity.createMany({
+ data: Array.from({ length: 501 }, () => ({
+ pollId,
+ type: "poll_closed",
+ payload: { reason: "auto" },
+ createdAt,
+ })),
+ });
+
+ const summary = await runCron(request);
+ expect(summary.fannedOut).toBe(501);
+ expect(
+ await prisma.webhookDelivery.count({ where: { webhookId: webhook.id } }),
+ ).toBe(501);
+ expect(
+ (
+ await prisma.spaceWebhook.findUniqueOrThrow({
+ where: { id: webhook.id },
+ })
+ ).cursor.getTime(),
+ ).toBeGreaterThan(createdAt.getTime());
+
+ const again = await runCron(request);
+ expect(again.fannedOut).toBe(0);
+ });
+
+ test("leaves activities inside the fan-out lag for the next run", async ({
+ request,
+ }) => {
+ const webhook = await createWebhook();
+ const activity = await createActivity({
+ type: "poll_closed",
+ payload: { reason: "auto" },
+ createdAt: new Date(),
+ });
+
+ const summary = await runCron(request);
+ expect(summary.fannedOut).toBe(0);
+ expect(receiver.requests).toHaveLength(0);
+
+ const updated = await prisma.spaceWebhook.findUniqueOrThrow({
+ where: { id: webhook.id },
+ });
+ expect(updated.cursor.getTime()).toBeLessThan(activity.createdAt.getTime());
+ });
+
+ test("schedules a retry after a failed attempt and succeeds on the next", async ({
+ request,
+ }) => {
+ const webhook = await createWebhook();
+ const activity = await createActivity({
+ type: "poll_closed",
+ payload: { reason: "manual" },
+ createdAt: secondsAgo(30),
+ });
+ receiver.status = 500;
+
+ const first = await runCron(request);
+ expect(first.failed).toBe(1);
+
+ const where = {
+ webhookId_activityId: { webhookId: webhook.id, activityId: activity.id },
+ };
+ const failed = await prisma.webhookDelivery.findUniqueOrThrow({ where });
+ expect(failed.status).toBe("failed");
+ expect(failed.attempts).toBe(1);
+ expect(failed.lastResponseStatus).toBe(500);
+ const delay = failed.nextAttemptAt.getTime() - Date.now();
+ expect(delay).toBeGreaterThan(45_000);
+ expect(delay).toBeLessThanOrEqual(60_000);
+ expect(
+ (
+ await prisma.spaceWebhook.findUniqueOrThrow({
+ where: { id: webhook.id },
+ })
+ ).lastFailedAt,
+ ).not.toBeNull();
+
+ // Not due yet: the next run must not retry it
+ const notDue = await runCron(request);
+ expect(notDue.failed + notDue.succeeded).toBe(0);
+ expect(receiver.requests).toHaveLength(1);
+
+ await prisma.webhookDelivery.update({
+ where,
+ data: { nextAttemptAt: secondsAgo(1) },
+ });
+ receiver.status = 200;
+
+ const second = await runCron(request);
+ expect(second.succeeded).toBe(1);
+ const succeeded = await prisma.webhookDelivery.findUniqueOrThrow({ where });
+ expect(succeeded.status).toBe("succeeded");
+ expect(succeeded.attempts).toBe(2);
+ expect(receiver.requests).toHaveLength(2);
+ // The retry resends the same event id
+ expect(JSON.parse(receiver.requests[1]?.body ?? "{}").id).toBe(activity.id);
+ });
+
+ test("exhausts a delivery after the final attempt and disables the endpoint after 20 in a row", async ({
+ request,
+ }) => {
+ const webhook = await createWebhook();
+ await prisma.spaceWebhook.update({
+ where: { id: webhook.id },
+ data: { consecutiveFailures: 18 },
+ });
+ const makeExhausting = async (activityId: string) =>
+ prisma.webhookDelivery.create({
+ data: {
+ webhookId: webhook.id,
+ activityId,
+ eventType: "poll.closed",
+ payload: { id: activityId, type: "poll.closed" },
+ status: "failed",
+ attempts: 5,
+ nextAttemptAt: secondsAgo(1),
+ },
+ });
+ const nineteenth = await makeExhausting("webhook-delivery-exhaust-1");
+ receiver.status = 503;
+
+ const first = await runCron(request);
+ expect(first.exhausted).toBe(1);
+ expect(
+ (
+ await prisma.webhookDelivery.findUniqueOrThrow({
+ where: { id: nineteenth.id },
+ })
+ ).status,
+ ).toBe("exhausted");
+ let updated = await prisma.spaceWebhook.findUniqueOrThrow({
+ where: { id: webhook.id },
+ });
+ expect(updated.consecutiveFailures).toBe(19);
+ expect(updated.enabled).toBe(true);
+
+ await makeExhausting("webhook-delivery-exhaust-2");
+ const second = await runCron(request);
+ expect(second.exhausted).toBe(1);
+ expect(second.disabled).toBe(1);
+ updated = await prisma.spaceWebhook.findUniqueOrThrow({
+ where: { id: webhook.id },
+ });
+ expect(updated.consecutiveFailures).toBe(20);
+ expect(updated.enabled).toBe(false);
+ });
+
+ test("a success resets the consecutive failure count", async ({
+ request,
+ }) => {
+ const webhook = await createWebhook();
+ await prisma.spaceWebhook.update({
+ where: { id: webhook.id },
+ data: { consecutiveFailures: 7 },
+ });
+ await createActivity({
+ type: "poll_reopened",
+ payload: {},
+ createdAt: secondsAgo(30),
+ });
+
+ await runCron(request);
+
+ expect(
+ (
+ await prisma.spaceWebhook.findUniqueOrThrow({
+ where: { id: webhook.id },
+ })
+ ).consecutiveFailures,
+ ).toBe(0);
+ });
+
+ test("reclaims in-flight deliveries orphaned by a dead run", async ({
+ request,
+ }) => {
+ const webhook = await createWebhook();
+ const payload = { id: "x", type: "poll.closed" };
+ const orphaned = await prisma.webhookDelivery.create({
+ data: {
+ webhookId: webhook.id,
+ activityId: "webhook-delivery-orphaned",
+ eventType: "poll.closed",
+ payload,
+ status: "in_flight",
+ attempts: 1,
+ updatedAt: secondsAgo(3 * 60),
+ },
+ });
+ const live = await prisma.webhookDelivery.create({
+ data: {
+ webhookId: webhook.id,
+ activityId: "webhook-delivery-live",
+ eventType: "poll.closed",
+ payload,
+ status: "in_flight",
+ attempts: 1,
+ },
+ });
+
+ const summary = await runCron(request);
+ expect(summary.reclaimed).toBe(1);
+ expect(summary.succeeded).toBe(1);
+
+ const delivered = await prisma.webhookDelivery.findUniqueOrThrow({
+ where: { id: orphaned.id },
+ });
+ expect(delivered.status).toBe("succeeded");
+ expect(delivered.attempts).toBe(2);
+ expect(
+ (
+ await prisma.webhookDelivery.findUniqueOrThrow({
+ where: { id: live.id },
+ })
+ ).status,
+ ).toBe("in_flight");
+ });
+});
diff --git a/packages/database/prisma/migrations/20260915120000_add_space_webhooks/migration.sql b/packages/database/prisma/migrations/20260915120000_add_space_webhooks/migration.sql
new file mode 100644
index 000000000..6d4208a1e
--- /dev/null
+++ b/packages/database/prisma/migrations/20260915120000_add_space_webhooks/migration.sql
@@ -0,0 +1,58 @@
+-- Poll webhooks: a space subscribes an HTTPS endpoint to poll lifecycle
+-- events. The poll activity log is the outbox; each webhook keeps a cursor
+-- into it and every fanned-out event becomes a delivery row that the
+-- dispatcher cron sends and retries.
+
+-- CreateEnum
+CREATE TYPE "webhook_delivery_status" AS ENUM ('pending', 'in_flight', 'succeeded', 'failed', 'exhausted');
+
+-- CreateTable
+CREATE TABLE "space_webhooks" (
+ "id" TEXT NOT NULL,
+ "space_id" TEXT NOT NULL,
+ "url" TEXT NOT NULL,
+ "secret" TEXT NOT NULL,
+ "events" TEXT[],
+ "enabled" BOOLEAN NOT NULL DEFAULT true,
+ "cursor" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ "last_delivered_at" TIMESTAMP(3),
+ "last_failed_at" TIMESTAMP(3),
+ "consecutive_failures" INTEGER NOT NULL DEFAULT 0,
+ "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ "updated_at" TIMESTAMP(3) NOT NULL,
+
+ CONSTRAINT "space_webhooks_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "webhook_deliveries" (
+ "id" TEXT NOT NULL,
+ "webhook_id" TEXT NOT NULL,
+ "activity_id" TEXT NOT NULL,
+ "event_type" TEXT NOT NULL,
+ "payload" JSONB NOT NULL,
+ "status" "webhook_delivery_status" NOT NULL DEFAULT 'pending',
+ "attempts" INTEGER NOT NULL DEFAULT 0,
+ "next_attempt_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ "last_response_status" INTEGER,
+ "last_error" TEXT,
+ "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ "updated_at" TIMESTAMP(3) NOT NULL,
+
+ CONSTRAINT "webhook_deliveries_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "space_webhooks_space_id_idx" ON "space_webhooks"("space_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "webhook_deliveries_webhook_id_activity_id_key" ON "webhook_deliveries"("webhook_id", "activity_id");
+
+-- CreateIndex
+CREATE INDEX "webhook_deliveries_status_next_attempt_at_idx" ON "webhook_deliveries"("status", "next_attempt_at");
+
+-- AddForeignKey
+ALTER TABLE "space_webhooks" ADD CONSTRAINT "space_webhooks_space_id_fkey" FOREIGN KEY ("space_id") REFERENCES "spaces"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "webhook_deliveries" ADD CONSTRAINT "webhook_deliveries_webhook_id_fkey" FOREIGN KEY ("webhook_id") REFERENCES "space_webhooks"("id") ON DELETE CASCADE ON UPDATE CASCADE;
diff --git a/packages/database/prisma/models/space.prisma b/packages/database/prisma/models/space.prisma
index 410a71f2c..01b702df7 100644
--- a/packages/database/prisma/models/space.prisma
+++ b/packages/database/prisma/models/space.prisma
@@ -42,6 +42,8 @@ model Space {
nonprofitApplications NonprofitApplication[]
+ webhooks SpaceWebhook[]
+
@@index([ownerId])
@@map("spaces")
}
@@ -119,3 +121,66 @@ model SpaceApiKey {
@@index([revokedAt], name: "space_api_key_revoked_idx")
@@map("space_api_keys")
}
+
+model SpaceWebhook {
+ id String @id @default(cuid())
+ spaceId String @map("space_id")
+ url String
+ /// AES-256-GCM under SECRET_PASSWORD (see @rallly/utils/encryption); the plaintext is shown once at creation
+ secret String
+ /// 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)
+ /// 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())
+
+ lastDeliveredAt DateTime? @map("last_delivered_at")
+ lastFailedAt DateTime? @map("last_failed_at")
+ /// Exhausted deliveries in a row; reset by any success. The dispatcher disables the endpoint once it reaches its cap
+ consecutiveFailures Int @default(0) @map("consecutive_failures")
+
+ createdAt DateTime @default(now()) @map("created_at")
+ updatedAt DateTime @updatedAt @map("updated_at")
+
+ space Space @relation(fields: [spaceId], references: [id], onDelete: Cascade)
+ deliveries WebhookDelivery[]
+
+ @@index([spaceId])
+ @@map("space_webhooks")
+}
+
+enum WebhookDeliveryStatus {
+ pending
+ in_flight
+ succeeded
+ failed
+ exhausted
+
+ @@map("webhook_delivery_status")
+}
+
+model WebhookDelivery {
+ id String @id @default(cuid())
+ webhookId String @map("webhook_id")
+ /// Soft reference to the PollActivity row this delivery was fanned out from; with webhookId it makes fan-out idempotent
+ activityId String @map("activity_id")
+ eventType String @map("event_type")
+ /// Frozen at fan-out: retries resend exactly what the first attempt sent
+ payload Json
+
+ status WebhookDeliveryStatus @default(pending)
+ attempts Int @default(0)
+ nextAttemptAt DateTime @default(now()) @map("next_attempt_at")
+
+ lastResponseStatus Int? @map("last_response_status")
+ lastError String? @map("last_error")
+
+ createdAt DateTime @default(now()) @map("created_at")
+ updatedAt DateTime @updatedAt @map("updated_at")
+
+ webhook SpaceWebhook @relation(fields: [webhookId], references: [id], onDelete: Cascade)
+
+ @@unique([webhookId, activityId])
+ @@index([status, nextAttemptAt])
+ @@map("webhook_deliveries")
+}