Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.
TypeScript i18nextnext-authnextjspostgresqlprismareact-emailt3-stacktailwindcsstrpcturborepotypescriptzod
✨ Deliver signed, retried poll webhooks from the activity log (#3297)
Luke Vella536f7e2252dc
diff --git a/apps/web/.env.test b/apps/web/.env.testindex b92753ba3..c1e7953e4 100644--- a/apps/web/.env.test+++ b/apps/web/.env.test@@ -16,3 +16,4 @@ SMTP_HOST=0.0.0.0SMTP_PORT=1025SMTP_REJECT_UNAUTHORIZED=false+WEBHOOK_ALLOW_PRIVATE_URLS=truediff --git a/apps/web/src/app/api/house-keeping/[...method]/route.ts b/apps/web/src/app/api/house-keeping/[...method]/route.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.sqlnew file mode 100644index 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.prismaindex 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")+}