Skip to content

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

✨ Send test events and show endpoint health in the webhooks list (#3346)

Luke Vella790c21cda159
diff --git a/apps/docs/api-reference/webhooks.mdx b/apps/docs/api-reference/webhooks.mdx
index c47595bfe..7aa6fb95e 100644
--- a/apps/docs/api-reference/webhooks.mdx
+++ b/apps/docs/api-reference/webhooks.mdx
@@ -22,6 +22,8 @@ Webhooks tell your own systems about poll and participant changes as they happen
A space can have up to five endpoints. A new endpoint starts receiving events from the moment it is created; history is never replayed.
+To check the endpoint before any poll changes, choose **Send test event** from its menu. Rallly sends a signed [`ping`](/api-reference/webhooks/events#test-events) and shows the response it got back.
+
## What an event carries
An event says what happened and to which poll or participant. It references both by id and carries only the facts that belong to the event itself: the reason a poll closed, the time it was scheduled for. It does not carry the poll's title, options or settings, or the participant's details. Fetch the API when you need them; the fetch returns the current state, where a snapshot in the event would already be stale by the time a retry lands.
@@ -34,7 +36,7 @@ Every delivery is a `POST` with a JSON body. Respond with any `2xx` status withi
Delivery is at least once. A delivery that fails is retried with backoff after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours; after the sixth failure it is exhausted and not retried. Failed deliveries never block later ones, so a burst of events can arrive out of order: sort on `createdAt` if order matters, and deduplicate on `id`, which retries of one event share.
-An endpoint that exhausts twenty deliveries in a row is disabled. Re-enable it from the settings page once the receiver is fixed; events that happened while it was disabled are not delivered.
+The settings page shows each endpoint's health. An endpoint is **Failing** once an attempt fails, and selecting that label shows the last error and response status. An endpoint that exhausts twenty deliveries in a row is turned off and shown as **Turned off after failures**. Fix the receiver, send a test event to confirm it, then turn the endpoint back on; events that happened while it was off are not delivered.
Every request is signed. Verify the signature before acting on a body; [Security](/api-reference/webhooks/security) shows how.
diff --git a/apps/docs/api-reference/webhooks/events.mdx b/apps/docs/api-reference/webhooks/events.mdx
index fa2a55faa..40eabe5f8 100644
--- a/apps/docs/api-reference/webhooks/events.mdx
+++ b/apps/docs/api-reference/webhooks/events.mdx
@@ -240,3 +240,19 @@ One event per transition. A poll that is closed, reopened and closed again produ
```
</Accordion>
</AccordionGroup>
+
+## Test events
+
+**Send test event** in the endpoint's menu on the settings page sends a `ping` to that endpoint straight away. It goes out whatever events the endpoint subscribes to, and it is signed and sent like any other event, so it checks your URL, your signature verification and your response in one go.
+
+```json
+{
+ "version": "2026-09-20",
+ "id": "ping_V1StGXR8Z5jdHi6BmyT",
+ "type": "ping",
+ "createdAt": "2025-01-12T08:30:00.000Z",
+ "data": {}
+}
+```
+
+A `ping` carries no data and is never retried. Respond with a `2xx` and otherwise ignore it. A failed test does not count toward disabling the endpoint.
diff --git a/apps/web/public/locales/en/app.json b/apps/web/public/locales/en/app.json
index 7747fd00a..bae84e6bb 100644
--- a/apps/web/public/locales/en/app.json
+++ b/apps/web/public/locales/en/app.json
@@ -997,17 +997,30 @@
"webhookDocs": "Webhook docs",
"webhookEventComboboxEmpty": "No events found",
"webhookEventCount": "{count, plural, one {# event} other {# events}}",
- "webhookLastDeliveryFailed": "Failed {date}",
- "webhookLastDeliveryFailedWithStatus": "Failed {date} with {status}",
+ "webhookHealthDisabledAfterFailures": "Turned off after failures",
+ "webhookHealthFailedInARow": "{count, plural, one {# event} other {# events}} failed in a row",
+ "webhookHealthFailing": "Failing",
+ "webhookHealthLastAttempt": "Last attempt {date}",
+ "webhookHealthLastAttemptFailed": "Last attempt failed",
+ "webhookHealthLastAttemptWithStatus": "Last attempt {date} returned {status}",
+ "webhookHealthRetryPolicy": "Rallly retries each event for up to {hours} hours and turns the endpoint off after {count} events in a row fail.",
+ "webhookHealthTurnBackOn": "Turn it back on to resume. Events from while it was off are not delivered.",
+ "webhookHealthTurnedOffByRallly": "Turned off by Rallly",
+ "webhookHealthTurnedOffReason": "{count} events in a row failed.",
"webhookLastDeliverySucceeded": "Delivered {date}",
"webhookLimitReached": "You've reached the maximum number of webhooks. Delete one before adding another.",
"webhooks": "Webhooks",
"webhooksBetaNotice": "Webhooks are in beta. Events and payloads may still change, and more events will be added.",
"webhooksDescription": "Send events to your own server",
"webhookSecretSecurityWarning": "Store this secret securely. Use it to verify that deliveries came from Rallly.",
+ "webhookSendTestEvent": "Send test event",
"webhooksSettingsDescription": "Send events to your own server with signed, retried deliveries.",
"webhooksUpgradeDescription": "Send events to your own server as things change in your space. Included with Pro.",
"webhooksUpgradeTitle": "Upgrade for webhooks",
+ "webhookTestEventDelivered": "Test event delivered",
+ "webhookTestEventFailed": "Test event failed",
+ "webhookTestEventRespondedWith": "Endpoint responded {status}",
+ "webhookTestEventSending": "Sending test event",
"webhookUrl": "URL",
"weekView": "Week view",
"whiteLabelAddon": "White Label Add-on",
diff --git a/apps/web/src/features/webhook/actions.ts b/apps/web/src/features/webhook/actions.ts
index b3a8f76a2..b88fe70fc 100644
--- a/apps/web/src/features/webhook/actions.ts
+++ b/apps/web/src/features/webhook/actions.ts
@@ -4,12 +4,21 @@ import { getActiveSpaceForUser } from "@/features/space/data";
import { loadOptionalUser } from "@/features/user/loaders";
import { AppError } from "@/lib/errors/app-error";
import { track } from "@/lib/posthog";
-import { authActionClient } from "@/lib/safe-action/server";
+import {
+ authActionClient,
+ createRateLimitMiddleware,
+} from "@/lib/safe-action/server";
import { getWebhookAccess } from "./data";
-import { createWebhook, deleteWebhook, setWebhookEnabled } from "./mutations";
+import {
+ createWebhook,
+ deleteWebhook,
+ sendWebhookTestEvent,
+ setWebhookEnabled,
+} from "./mutations";
import {
createWebhookInputSchema,
deleteWebhookSchema,
+ sendWebhookTestEventSchema,
setWebhookEnabledSchema,
} from "./schema";
@@ -108,3 +117,29 @@ export const deleteWebhookAction = authActionClient
},
});
});
+
+// Each call is an outbound request to a URL the owner chose, so it is
+// limited: enough to fix a receiver and try again, not enough to use Rallly
+// to hammer someone else's server.
+export const sendWebhookTestEventAction = authActionClient
+ .metadata({ actionName: "send_webhook_test_event" })
+ .inputSchema(sendWebhookTestEventSchema)
+ .use(createRateLimitMiddleware(10, "1 m"))
+ .action(async ({ ctx, parsedInput }) => {
+ const { space } = await requireWebhookAccess();
+
+ const result = await sendWebhookTestEvent({
+ spaceId: space.id,
+ webhookId: parsedInput.webhookId,
+ });
+
+ track(ctx.user, {
+ event: "developer:webhook_test_send",
+ properties: { ok: result.ok, status: result.status },
+ groups: {
+ space: space.id,
+ },
+ });
+
+ return result;
+ });
diff --git a/apps/web/src/features/webhook/components/webhook-actions.tsx b/apps/web/src/features/webhook/components/webhook-actions.tsx
index 06d6f80a7..c571bd9ea 100644
--- a/apps/web/src/features/webhook/components/webhook-actions.tsx
+++ b/apps/web/src/features/webhook/components/webhook-actions.tsx
@@ -19,10 +19,14 @@ import {
} from "@rallly/ui/dropdown-menu";
import { toast } from "@rallly/ui/sonner";
import { Switch } from "@rallly/ui/switch";
-import { MoreVerticalIcon, Trash2Icon } from "lucide-react";
+import { MoreVerticalIcon, SendIcon, Trash2Icon } from "lucide-react";
import { Trans, useTranslation } from "@/i18n/client";
import { useSafeAction } from "@/lib/safe-action/client";
-import { deleteWebhookAction, setWebhookEnabledAction } from "../actions";
+import {
+ deleteWebhookAction,
+ sendWebhookTestEventAction,
+ setWebhookEnabledAction,
+} from "../actions";
export function WebhookActions({
webhookId,
@@ -37,6 +41,42 @@ export function WebhookActions({
const deleteDialog = useDialog();
const setEnabled = useSafeAction(setWebhookEnabledAction);
+ const sendTestEvent = useSafeAction(sendWebhookTestEventAction, {
+ onExecute: () => {
+ toast.loading(
+ t("webhookTestEventSending", { defaultValue: "Sending test event" }),
+ { id: `webhook-test-${webhookId}` },
+ );
+ },
+ onSuccess: ({ data }) => {
+ if (!data) {
+ return;
+ }
+ const id = `webhook-test-${webhookId}`;
+ if (data.ok) {
+ toast.success(
+ t("webhookTestEventDelivered", {
+ defaultValue: "Test event delivered",
+ }),
+ {
+ id,
+ description: t("webhookTestEventRespondedWith", {
+ defaultValue: "Endpoint responded {status}",
+ status: data.status,
+ }),
+ },
+ );
+ } else {
+ toast.error(
+ t("webhookTestEventFailed", { defaultValue: "Test event failed" }),
+ { id, description: data.error },
+ );
+ }
+ },
+ onError: () => {
+ toast.dismiss(`webhook-test-${webhookId}`);
+ },
+ });
const deleteWebhook = useSafeAction(deleteWebhookAction, {
onSuccess: () => {
toast.success(t("webhookDeleted", { defaultValue: "Webhook deleted" }));
@@ -69,6 +109,15 @@ export function WebhookActions({
<MoreVerticalIcon className="text-muted-foreground" />
</DropdownMenuTrigger>
<DropdownMenuContent align="end">
+ <DropdownMenuItem
+ disabled={sendTestEvent.isExecuting}
+ onClick={() => {
+ sendTestEvent.execute({ webhookId });
+ }}
+ >
+ <SendIcon />
+ <Trans i18nKey="webhookSendTestEvent" defaults="Send test event" />
+ </DropdownMenuItem>
<DropdownMenuItem
onClick={() => {
deleteDialog.trigger();
diff --git a/apps/web/src/features/webhook/components/webhook-health.tsx b/apps/web/src/features/webhook/components/webhook-health.tsx
new file mode 100644
index 000000000..811ced4b3
--- /dev/null
+++ b/apps/web/src/features/webhook/components/webhook-health.tsx
@@ -0,0 +1,190 @@
+"use client";
+
+import { Badge, badgeVariants } from "@rallly/ui/badge";
+import {
+ Popover,
+ PopoverContent,
+ PopoverDescription,
+ PopoverHeader,
+ PopoverTitle,
+ PopoverTrigger,
+} from "@rallly/ui/popover";
+import { CircleCheckIcon, CircleXIcon, TriangleAlertIcon } from "lucide-react";
+import { Trans } from "@/i18n/client";
+import { useDateTime } from "@/lib/datetime/client";
+import { MAX_CONSECUTIVE_FAILURES, RETRY_DELAYS_MS } from "../constants";
+import { getWebhookHealth } from "../utils";
+
+const RETRY_WINDOW_HOURS = Math.ceil(
+ RETRY_DELAYS_MS.reduce((total, delay) => total + delay, 0) / 3_600_000,
+);
+
+type LastAttempt = {
+ status: "succeeded" | "failed" | "exhausted" | "pending" | "in_flight";
+ lastResponseStatus: number | null;
+ lastError: string | null;
+ updatedAt: Date;
+};
+
+function LastAttemptDetails({ lastAttempt }: { lastAttempt?: LastAttempt }) {
+ const { toRelativeTime } = useDateTime();
+
+ if (!lastAttempt) {
+ return null;
+ }
+
+ return (
+ <div className="flex flex-col gap-1.5">
+ <p className="text-muted-foreground">
+ {lastAttempt.lastResponseStatus ? (
+ <Trans
+ i18nKey="webhookHealthLastAttemptWithStatus"
+ defaults="Last attempt {date} returned {status}"
+ values={{
+ date: toRelativeTime(lastAttempt.updatedAt),
+ status: lastAttempt.lastResponseStatus,
+ }}
+ />
+ ) : (
+ <Trans
+ i18nKey="webhookHealthLastAttempt"
+ defaults="Last attempt {date}"
+ values={{ date: toRelativeTime(lastAttempt.updatedAt) }}
+ />
+ )}
+ </p>
+ {lastAttempt.lastError ? (
+ <p className="break-words rounded-md bg-muted px-2 py-1.5 font-mono text-muted-foreground text-xs">
+ {lastAttempt.lastError}
+ </p>
+ ) : null}
+ </div>
+ );
+}
+
+/**
+ * An endpoint's health in the settings list. An icon and its own words carry
+ * the state; the color only reinforces it. The failure states open the last
+ * error in place. An endpoint the owner switched off shows nothing: the
+ * switch beside it already says so.
+ */
+export function WebhookHealth({
+ enabled,
+ consecutiveFailures,
+ lastAttempt,
+}: {
+ enabled: boolean;
+ consecutiveFailures: number;
+ lastAttempt?: LastAttempt;
+}) {
+ const { toRelativeTime } = useDateTime();
+ const health = getWebhookHealth({
+ enabled,
+ consecutiveFailures,
+ lastAttempt,
+ });
+
+ switch (health) {
+ case "disabled":
+ return null;
+ case "idle":
+ return (
+ <div className="text-muted-foreground text-sm">
+ <Trans i18nKey="noDeliveriesYet" defaults="No deliveries yet" />
+ </div>
+ );
+ case "healthy":
+ return (
+ <Badge variant="green">
+ <CircleCheckIcon className="mr-1 size-3.5" />
+ {lastAttempt ? (
+ <Trans
+ i18nKey="webhookLastDeliverySucceeded"
+ defaults="Delivered {date}"
+ values={{ date: toRelativeTime(lastAttempt.updatedAt) }}
+ />
+ ) : null}
+ </Badge>
+ );
+ case "failing":
+ return (
+ <Popover>
+ <PopoverTrigger
+ className={badgeVariants({ variant: "amber" })}
+ render={<button type="button" />}
+ >
+ <TriangleAlertIcon className="mr-1 size-3.5" />
+ <Trans i18nKey="webhookHealthFailing" defaults="Failing" />
+ </PopoverTrigger>
+ <PopoverContent align="end">
+ <PopoverHeader>
+ <PopoverTitle>
+ {consecutiveFailures > 0 ? (
+ <Trans
+ i18nKey="webhookHealthFailedInARow"
+ defaults="{count, plural, one {# event} other {# events}} failed in a row"
+ values={{ count: consecutiveFailures }}
+ />
+ ) : (
+ <Trans
+ i18nKey="webhookHealthLastAttemptFailed"
+ defaults="Last attempt failed"
+ />
+ )}
+ </PopoverTitle>
+ </PopoverHeader>
+ <LastAttemptDetails lastAttempt={lastAttempt} />
+ <PopoverDescription>
+ <Trans
+ i18nKey="webhookHealthRetryPolicy"
+ defaults="Rallly retries each event for up to {hours} hours and turns the endpoint off after {count} events in a row fail."
+ values={{
+ hours: RETRY_WINDOW_HOURS,
+ count: MAX_CONSECUTIVE_FAILURES,
+ }}
+ />
+ </PopoverDescription>
+ </PopoverContent>
+ </Popover>
+ );
+ case "disabled_after_failures":
+ return (
+ <Popover>
+ <PopoverTrigger
+ className={badgeVariants({ variant: "destructive" })}
+ render={<button type="button" />}
+ >
+ <CircleXIcon className="mr-1 size-3.5" />
+ <Trans
+ i18nKey="webhookHealthDisabledAfterFailures"
+ defaults="Turned off after failures"
+ />
+ </PopoverTrigger>
+ <PopoverContent align="end">
+ <PopoverHeader>
+ <PopoverTitle>
+ <Trans
+ i18nKey="webhookHealthTurnedOffByRallly"
+ defaults="Turned off by Rallly"
+ />
+ </PopoverTitle>
+ <PopoverDescription>
+ <Trans
+ i18nKey="webhookHealthTurnedOffReason"
+ defaults="{count} events in a row failed."
+ values={{ count: consecutiveFailures }}
+ />
+ </PopoverDescription>
+ </PopoverHeader>
+ <LastAttemptDetails lastAttempt={lastAttempt} />
+ <p className="text-muted-foreground">
+ <Trans
+ i18nKey="webhookHealthTurnBackOn"
+ defaults="Turn it back on to resume. Events from while it was off are not delivered."
+ />
+ </p>
+ </PopoverContent>
+ </Popover>
+ );
+ }
+}
diff --git a/apps/web/src/features/webhook/components/webhook-last-delivery.tsx b/apps/web/src/features/webhook/components/webhook-last-delivery.tsx
deleted file mode 100644
index 43ebabb70..000000000
--- a/apps/web/src/features/webhook/components/webhook-last-delivery.tsx
+++ /dev/null
@@ -1,63 +0,0 @@
-"use client";
-
-import { CircleCheckIcon, CircleXIcon } from "lucide-react";
-import { Trans } from "@/i18n/client";
-import { useDateTime } from "@/lib/datetime/client";
-
-/**
- * Outcome of the webhook's last attempted delivery. An icon and its own
- * words carry the state; the color only reinforces it.
- */
-export function WebhookLastDelivery({
- delivery,
-}: {
- delivery?: {
- status: "succeeded" | "failed" | "exhausted" | "pending" | "in_flight";
- lastResponseStatus: number | null;
- updatedAt: Date;
- };
-}) {
- const { toRelativeTime } = useDateTime();
-
- if (!delivery) {
- return (
- <div className="text-muted-foreground text-sm">
- <Trans i18nKey="noDeliveriesYet" defaults="No deliveries yet" />
- </div>
- );
- }
-
- const when = toRelativeTime(delivery.updatedAt);
-
- if (delivery.status === "succeeded") {
- return (
- <div className="flex items-center gap-1.5 text-muted-foreground text-sm">
- <CircleCheckIcon className="size-4 shrink-0 text-green-600" />
- <Trans
- i18nKey="webhookLastDeliverySucceeded"
- defaults="Delivered {date}"
- values={{ date: when }}
- />
- </div>
- );
- }
-
- return (
- <div className="flex items-center gap-1.5 text-muted-foreground text-sm">
- <CircleXIcon className="size-4 shrink-0 text-destructive" />
- {delivery.lastResponseStatus ? (
- <Trans
- i18nKey="webhookLastDeliveryFailedWithStatus"
- defaults="Failed {date} with {status}"
- values={{ date: when, status: delivery.lastResponseStatus }}
- />
- ) : (
- <Trans
- i18nKey="webhookLastDeliveryFailed"
- defaults="Failed {date}"
- values={{ date: when }}
- />
- )}
- </div>
- );
-}
diff --git a/apps/web/src/features/webhook/components/webhooks-list.tsx b/apps/web/src/features/webhook/components/webhooks-list.tsx
index 245e3a55a..d9a81ae9d 100644
--- a/apps/web/src/features/webhook/components/webhooks-list.tsx
+++ b/apps/web/src/features/webhook/components/webhooks-list.tsx
@@ -11,7 +11,7 @@ import { StackedList, StackedListItem } from "@/components/stacked-list";
import { Trans } from "@/i18n/client";
import type { getSpaceWebhooks } from "../data";
import { WebhookActions } from "./webhook-actions";
-import { WebhookLastDelivery } from "./webhook-last-delivery";
+import { WebhookHealth } from "./webhook-health";
type Webhook = Awaited<ReturnType<typeof getSpaceWebhooks>>[number];
@@ -58,7 +58,11 @@ export function WebhooksList({ webhooks }: { webhooks: Webhook[] }) {
</div>
</div>
</div>
- <WebhookLastDelivery delivery={webhook.deliveries[0]} />
+ <WebhookHealth
+ enabled={webhook.enabled}
+ consecutiveFailures={webhook.consecutiveFailures}
+ lastAttempt={webhook.deliveries[0]}
+ />
<WebhookActions
webhookId={webhook.id}
webhookUrl={webhook.url}
diff --git a/apps/web/src/features/webhook/data.ts b/apps/web/src/features/webhook/data.ts
index 38a900a07..18f641aed 100644
--- a/apps/web/src/features/webhook/data.ts
+++ b/apps/web/src/features/webhook/data.ts
@@ -32,8 +32,9 @@ export function getWebhookAccess(
/**
* A space's endpoints for the settings list. The last attempt's outcome comes
- * from the most recent delivery that was actually attempted, so an endpoint
- * with a queue of pending rows still shows the result the owner last saw.
+ * from the most recent delivery that was actually attempted, test events
+ * included, so an endpoint with a queue of pending rows still shows the
+ * result the owner last saw.
*/
export async function getSpaceWebhooks({
spaceId,
@@ -47,12 +48,14 @@ export async function getSpaceWebhooks({
url: true,
events: true,
enabled: true,
+ consecutiveFailures: true,
createdAt: true,
deliveries: {
where: { status: { in: ["succeeded", "failed", "exhausted"] } },
select: {
status: true,
lastResponseStatus: true,
+ lastError: true,
updatedAt: true,
},
orderBy: { updatedAt: "desc" },
diff --git a/apps/web/src/features/webhook/mutations.ts b/apps/web/src/features/webhook/mutations.ts
index e79b1f4ff..21addc298 100644
--- a/apps/web/src/features/webhook/mutations.ts
+++ b/apps/web/src/features/webhook/mutations.ts
@@ -7,6 +7,7 @@ import { prisma } from "@rallly/database";
import { createLogger } from "@rallly/logger";
import { decrypt, encrypt } from "@rallly/utils/encryption";
import { Clock, Data, Effect } from "effect";
+import { nanoid } from "nanoid";
import { after } from "next/server";
import { env } from "@/env";
import { resolveSpaceTier } from "@/features/billing/utils";
@@ -38,6 +39,7 @@ import { MAX_WEBHOOKS_PER_SPACE } from "./schema";
import { WebhookSender } from "./service";
import {
buildWebhookPayload,
+ buildWebhookTestPayload,
getRetryDelayMs,
toWebhookEventType,
} from "./utils";
@@ -611,6 +613,80 @@ export async function setWebhookEnabled({
});
}
+/**
+ * Sends a `ping` to one endpoint now, through the same signing and sender
+ * as any delivery, and returns what came back. A diagnostic, not an event:
+ * one attempt and no retry, and a failure never counts toward disabling the
+ * endpoint, so testing a broken receiver cannot turn it off. On an enabled
+ * endpoint a success resets the count as any success does: the endpoint has
+ * just proven it accepts deliveries. On a disabled one the count stays, since
+ * it is what marks the endpoint as turned off by the dispatcher rather than
+ * by its owner; re-enabling clears it.
+ *
+ * The row is written after the attempt, never as in flight: stale
+ * reclamation would otherwise hand a ping orphaned by a crash to the
+ * dispatcher, which would retry it and count its exhaustion. A failure is
+ * recorded as exhausted for the same reason. The activity id is the event
+ * id, since no activity produced it.
+ */
+export async function sendWebhookTestEvent({
+ spaceId,
+ webhookId,
+}: {
+ spaceId: string;
+ webhookId: string;
+}) {
+ await authorizeWebhook({ spaceId, webhookId, action: "update" });
+
+ const webhook = await prisma.spaceWebhook.findUniqueOrThrow({
+ where: { id: webhookId },
+ select: { url: true, secret: true },
+ });
+
+ const id = `ping_${nanoid()}`;
+ const now = new Date();
+ const payload = buildWebhookTestPayload({ id, createdAt: now });
+
+ const result = await runtime.runPromise(
+ attemptDelivery({
+ id,
+ eventType: payload.type,
+ payload,
+ webhook,
+ }).pipe(Effect.provide(WebhookSender.layer)),
+ );
+
+ await prisma.$transaction([
+ prisma.webhookDelivery.create({
+ data: {
+ id,
+ webhookId,
+ activityId: id,
+ eventType: payload.type,
+ payload: payload as unknown as Prisma.InputJsonObject,
+ status: result.ok ? "succeeded" : "exhausted",
+ attempts: 1,
+ lastResponseStatus: result.status,
+ lastError: result.ok ? null : result.error,
+ },
+ }),
+ ...(result.ok
+ ? [
+ prisma.spaceWebhook.update({
+ where: { id: webhookId },
+ data: { lastDeliveredAt: now },
+ }),
+ prisma.spaceWebhook.updateMany({
+ where: { id: webhookId, enabled: true },
+ data: { consecutiveFailures: 0 },
+ }),
+ ]
+ : []),
+ ]);
+
+ return result;
+}
+
export async function deleteWebhook({
spaceId,
webhookId,
diff --git a/apps/web/src/features/webhook/schema.ts b/apps/web/src/features/webhook/schema.ts
index 3ec4326ed..1d54c6893 100644
--- a/apps/web/src/features/webhook/schema.ts
+++ b/apps/web/src/features/webhook/schema.ts
@@ -236,6 +236,26 @@ export const webhookEventSchema = z
export type WebhookEvent = z.infer<typeof webhookEventSchema>;
+/**
+ * Sent only by "Send test event" in the settings page, to that one endpoint,
+ * whatever it subscribes to. Deliberately outside `webhookEventTypeSchema`:
+ * it is not something an endpoint subscribes to, so it never appears in the
+ * picker and a test never fails for want of a subscription.
+ */
+export const webhookPingEventSchema = z
+ .object({
+ ...envelope,
+ type: z.literal("ping"),
+ data: z.object({}),
+ })
+ .meta({
+ id: "WebhookPingEvent",
+ description:
+ "A test event sent from the webhooks settings page. It carries no data; respond with a 2xx and otherwise ignore it.",
+ });
+
+export type WebhookPingEvent = z.infer<typeof webhookPingEventSchema>;
+
const rejectionMessages = {
invalid: "Enter a valid URL",
insecure_scheme: "Webhook URLs must use https",
@@ -290,3 +310,7 @@ export const setWebhookEnabledSchema = z.object({
export const deleteWebhookSchema = z.object({
webhookId: z.string(),
});
+
+export const sendWebhookTestEventSchema = z.object({
+ webhookId: z.string(),
+});
diff --git a/apps/web/src/features/webhook/utils.test.ts b/apps/web/src/features/webhook/utils.test.ts
index 434e23ded..e57c13848 100644
--- a/apps/web/src/features/webhook/utils.test.ts
+++ b/apps/web/src/features/webhook/utils.test.ts
@@ -1,8 +1,12 @@
import { createHmac } from "node:crypto";
import { describe, expect, it } from "vitest";
+import { MAX_CONSECUTIVE_FAILURES, WEBHOOK_VERSION } from "./constants";
+import { webhookPingEventSchema } from "./schema";
import {
buildWebhookPayload,
+ buildWebhookTestPayload,
getRetryDelayMs,
+ getWebhookHealth,
isPrivateAddress,
signWebhookBody,
toWebhookEventType,
@@ -261,6 +265,78 @@ describe("buildWebhookPayload", () => {
});
});
+describe("buildWebhookTestPayload", () => {
+ it("builds a ping in the shared envelope with no data", () => {
+ const payload = buildWebhookTestPayload({
+ id: "ping_abc",
+ createdAt: new Date("2026-09-23T10:00:00.000Z"),
+ });
+ expect(payload).toEqual({
+ version: WEBHOOK_VERSION,
+ id: "ping_abc",
+ type: "ping",
+ createdAt: "2026-09-23T10:00:00.000Z",
+ data: {},
+ });
+ expect(webhookPingEventSchema.safeParse(payload).success).toBe(true);
+ });
+});
+
+describe("getWebhookHealth", () => {
+ it("is idle when enabled and nothing has been attempted", () => {
+ expect(getWebhookHealth({ enabled: true, consecutiveFailures: 0 })).toBe(
+ "idle",
+ );
+ });
+
+ it("is healthy when the last attempt succeeded", () => {
+ expect(
+ getWebhookHealth({
+ enabled: true,
+ consecutiveFailures: 0,
+ lastAttempt: { status: "succeeded" },
+ }),
+ ).toBe("healthy");
+ });
+
+ it("is failing as soon as an attempt fails, before any event exhausts", () => {
+ expect(
+ getWebhookHealth({
+ enabled: true,
+ consecutiveFailures: 0,
+ lastAttempt: { status: "failed" },
+ }),
+ ).toBe("failing");
+ });
+
+ it("is failing while exhausted events are counted against it", () => {
+ expect(
+ getWebhookHealth({
+ enabled: true,
+ consecutiveFailures: 3,
+ lastAttempt: { status: "succeeded" },
+ }),
+ ).toBe("failing");
+ });
+
+ it("tells a dispatcher disable apart from an owner disable", () => {
+ expect(
+ getWebhookHealth({
+ enabled: false,
+ consecutiveFailures: MAX_CONSECUTIVE_FAILURES,
+ lastAttempt: { status: "exhausted" },
+ }),
+ ).toBe("disabled_after_failures");
+ expect(
+ getWebhookHealth({
+ enabled: false,
+ consecutiveFailures: 4,
+ lastAttempt: { status: "failed" },
+ }),
+ ).toBe("disabled");
+ });
+});
+
describe("isPrivateAddress", () => {
it.each([
"127.0.0.1",
diff --git a/apps/web/src/features/webhook/utils.ts b/apps/web/src/features/webhook/utils.ts
index 89d7e2ba1..9c744f820 100644
--- a/apps/web/src/features/webhook/utils.ts
+++ b/apps/web/src/features/webhook/utils.ts
@@ -1,6 +1,14 @@
import { pollActivitySchema } from "@/features/activity/schema";
-import { RETRY_DELAYS_MS, WEBHOOK_VERSION } from "./constants";
-import type { WebhookEvent, WebhookEventType } from "./schema";
+import {
+ MAX_CONSECUTIVE_FAILURES,
+ RETRY_DELAYS_MS,
+ WEBHOOK_VERSION,
+} from "./constants";
+import type {
+ WebhookEvent,
+ WebhookEventType,
+ WebhookPingEvent,
+} from "./schema";
/**
* The resource half of an event name (`poll` in `poll.closed`). Event names
@@ -240,6 +248,62 @@ export function buildWebhookPayload({
}
}
+/** The body of a test event: the shared envelope and nothing else. */
+export function buildWebhookTestPayload({
+ id,
+ createdAt,
+}: {
+ id: string;
+ createdAt: Date;
+}): WebhookPingEvent {
+ return {
+ version: WEBHOOK_VERSION,
+ id,
+ type: "ping",
+ createdAt: createdAt.toISOString(),
+ data: {},
+ };
+}
+
+export type WebhookHealth =
+ | "healthy"
+ | "failing"
+ | "disabled_after_failures"
+ | "disabled"
+ | "idle";
+
+/**
+ * An endpoint's state as the settings list presents it. Disabled by the
+ * dispatcher and disabled by the owner share `enabled: false`; they are told
+ * apart by the failure count, which only the dispatcher raises to the cap and
+ * which re-enabling clears. Failing is either signal: exhausted events count
+ * against the endpoint, but exhaustion takes the whole retry schedule, so a
+ * receiver that has been down for hours shows up first as a failed attempt.
+ */
+export function getWebhookHealth({
+ enabled,
+ consecutiveFailures,
+ lastAttempt,
+}: {
+ enabled: boolean;
+ consecutiveFailures: number;
+ lastAttempt?: { status: string };
+}): WebhookHealth {
+ if (!enabled) {
+ return consecutiveFailures >= MAX_CONSECUTIVE_FAILURES
+ ? "disabled_after_failures"
+ : "disabled";
+ }
+ if (
+ consecutiveFailures > 0 ||
+ lastAttempt?.status === "failed" ||
+ lastAttempt?.status === "exhausted"
+ ) {
+ return "failing";
+ }
+ return lastAttempt ? "healthy" : "idle";
+}
+
function parseIPv4(address: string) {
const parts = address.split(".");
if (parts.length !== 4) {
diff --git a/apps/web/tests/webhooks-settings.spec.ts b/apps/web/tests/webhooks-settings.spec.ts
index 1ccd0f3ba..9f6c4edbb 100644
--- a/apps/web/tests/webhooks-settings.spec.ts
+++ b/apps/web/tests/webhooks-settings.spec.ts
@@ -1,8 +1,15 @@
+import { createHmac } from "node:crypto";
+import type { Server } from "node:http";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
import type { Page } from "@playwright/test";
import { expect, test } from "@playwright/test";
import { prisma } from "@rallly/database";
import { decrypt, encrypt } from "@rallly/utils/encryption";
-import { WEBHOOK_VERSION } from "@/features/webhook/constants";
+import {
+ MAX_CONSECUTIVE_FAILURES,
+ WEBHOOK_VERSION,
+} from "@/features/webhook/constants";
import { WEBHOOK_EVENT_TYPES } from "@/features/webhook/schema";
import {
createUserInDb,
@@ -12,8 +19,9 @@ import {
/**
* The webhooks settings page: adding an endpoint and revealing its signing
- * secret once, disabling one, deleting one, and the two states that deny
- * access — a member of the space, and a space still on the hobby tier.
+ * secret once, disabling one, deleting one, its health and a test event,
+ * and the two states that deny access — a member of the space, and a space
+ * still on the hobby tier.
*/
const runId = Date.now().toString(36);
@@ -44,24 +52,80 @@ async function createOwner(name: string, { pro }: { pro: boolean }) {
return { user, space, email };
}
+const WEBHOOK_SECRET = "whsec_settings_test";
+
async function createWebhookInDb({
spaceId,
url,
+ enabled = true,
+ consecutiveFailures = 0,
}: {
spaceId: string;
url: string;
+ enabled?: boolean;
+ consecutiveFailures?: number;
}) {
return prisma.spaceWebhook.create({
data: {
spaceId,
url,
- secret: encrypt("whsec_settings_test", SECRET_PASSWORD),
+ secret: encrypt(WEBHOOK_SECRET, SECRET_PASSWORD),
events: ["poll.closed", "poll.reopened", "poll.scheduled"],
version: WEBHOOK_VERSION,
+ enabled,
+ consecutiveFailures,
},
});
}
+async function createAttemptInDb({
+ webhookId,
+ status,
+ lastResponseStatus,
+ lastError,
+}: {
+ webhookId: string;
+ status: "succeeded" | "failed" | "exhausted";
+ lastResponseStatus: number | null;
+ lastError: string | null;
+}) {
+ return prisma.webhookDelivery.create({
+ data: {
+ webhookId,
+ activityId: `webhooks-settings-${runId}-${webhookId}`,
+ eventType: "poll.closed",
+ payload: { type: "poll.closed" },
+ status,
+ attempts: 1,
+ lastResponseStatus,
+ lastError,
+ },
+ });
+}
+
+/** A loopback endpoint answering every request with `status`. */
+async function startReceiver(status: number) {
+ const requests: { headers: Record<string, unknown>; body: string }[] = [];
+ const server: Server = createServer((req, res) => {
+ let body = "";
+ req.on("data", (chunk) => {
+ body += chunk;
+ });
+ req.on("end", () => {
+ requests.push({ headers: req.headers, body });
+ res.statusCode = status;
+ res.end();
+ });
+ });
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ const { port } = server.address() as AddressInfo;
+ return {
+ url: `http://127.0.0.1:${port}/hook`,
+ requests,
+ stop: () => new Promise<void>((resolve) => server.close(() => resolve())),
+ };
+}
+
function decryptSecret(stored: string) {
return decrypt(stored, SECRET_PASSWORD);
}
@@ -209,29 +273,252 @@ test.describe("Webhooks settings", () => {
).toBe(0);
});
- test("shows the last delivery result for an endpoint", async ({ page }) => {
- const { space, email } = await createOwner("webhooks-delivery", {
+ test("shows a failing endpoint and its last error in place", async ({
+ page,
+ }) => {
+ const { space, email } = await createOwner("webhooks-failing", {
pro: true,
});
- const url = "https://example.com/hooks/delivery";
+ const url = "https://example.com/hooks/failing";
const webhook = await createWebhookInDb({ spaceId: space.id, url });
- await prisma.webhookDelivery.create({
- data: {
- webhookId: webhook.id,
- activityId: `webhooks-settings-${runId}`,
- eventType: "poll.closed",
- payload: { type: "poll.closed" },
- status: "failed",
- attempts: 1,
- lastResponseStatus: 500,
- },
+ // A retry is still scheduled, so nothing has exhausted yet: the failed
+ // attempt alone is what marks the endpoint failing.
+ await createAttemptInDb({
+ webhookId: webhook.id,
+ status: "failed",
+ lastResponseStatus: 500,
+ lastError: "HTTP 500",
});
await gotoWebhooks(page, email);
+ await endpointRow(page, url)
+ .getByRole("button", { name: "Failing" })
+ .click();
+ const popover = page.getByRole("dialog");
+ await expect(popover.getByText("Last attempt failed")).toBeVisible();
+ await expect(popover.getByText(/returned 500/)).toBeVisible();
+ await expect(popover.getByText("HTTP 500")).toBeVisible();
+ });
+
+ test("tells an endpoint Rallly turned off apart from one the owner did", async ({
+ page,
+ }) => {
+ const { space, email } = await createOwner("webhooks-turned-off", {
+ pro: true,
+ });
+ const turnedOffUrl = "https://example.com/hooks/turned-off";
+ const turnedOff = await createWebhookInDb({
+ spaceId: space.id,
+ url: turnedOffUrl,
+ enabled: false,
+ consecutiveFailures: MAX_CONSECUTIVE_FAILURES,
+ });
+ await createAttemptInDb({
+ webhookId: turnedOff.id,
+ status: "exhausted",
+ lastResponseStatus: null,
+ lastError: "getaddrinfo ENOTFOUND example.invalid",
+ });
+ const switchedOffUrl = "https://example.com/hooks/switched-off";
+ await createWebhookInDb({
+ spaceId: space.id,
+ url: switchedOffUrl,
+ enabled: false,
+ });
+
+ await gotoWebhooks(page, email);
+
+ // The owner's own choice is the switch; nothing repeats it.
+ await expect(
+ endpointRow(page, switchedOffUrl).getByRole("button", {
+ name: "Turned off after failures",
+ }),
+ ).toHaveCount(0);
+
+ await endpointRow(page, turnedOffUrl)
+ .getByRole("button", { name: "Turned off after failures" })
+ .click();
+ const popover = page.getByRole("dialog");
+ await expect(popover.getByText("Turned off by Rallly")).toBeVisible();
await expect(
- endpointRow(page, url).getByText(/Failed .* with 500/),
+ popover.getByText("getaddrinfo ENOTFOUND example.invalid"),
).toBeVisible();
+
+ // Turning it back on clears the count, so it is no longer shown as
+ // turned off by Rallly.
+ await page.keyboard.press("Escape");
+ await endpointRow(page, turnedOffUrl)
+ .getByRole("switch", { name: "Enabled" })
+ .click();
+ await expect
+ .poll(
+ async () =>
+ (
+ await prisma.spaceWebhook.findUniqueOrThrow({
+ where: { id: turnedOff.id },
+ })
+ ).consecutiveFailures,
+ )
+ .toBe(0);
+ });
+
+ test("sends a signed test event and reports the response", async ({
+ page,
+ }) => {
+ const receiver = await startReceiver(204);
+ try {
+ const { space, email } = await createOwner("webhooks-test-event", {
+ pro: true,
+ });
+ const webhook = await createWebhookInDb({
+ spaceId: space.id,
+ url: receiver.url,
+ consecutiveFailures: 3,
+ });
+
+ await gotoWebhooks(page, email);
+
+ await endpointRow(page, receiver.url)
+ .getByRole("button", { name: "More options" })
+ .click();
+ await page.getByRole("menuitem", { name: "Send test event" }).click();
+
+ await expect(page.getByText("Test event delivered")).toBeVisible();
+ await expect(page.getByText("Endpoint responded 204")).toBeVisible();
+
+ expect(receiver.requests).toHaveLength(1);
+ const [request] = receiver.requests;
+ const body = JSON.parse(request?.body ?? "{}");
+ expect(body).toMatchObject({
+ version: WEBHOOK_VERSION,
+ type: "ping",
+ data: {},
+ });
+ expect(request?.headers["x-rallly-event"]).toBe("ping");
+ const [t, v1] = String(request?.headers["x-rallly-signature"])
+ .split(",")
+ .map((part) => part.split("=")[1]);
+ expect(v1).toBe(
+ createHmac("sha256", WEBHOOK_SECRET)
+ .update(`${t}.${request?.body}`)
+ .digest("hex"),
+ );
+
+ const delivery = await prisma.webhookDelivery.findFirstOrThrow({
+ where: { webhookId: webhook.id },
+ });
+ expect(delivery).toMatchObject({
+ eventType: "ping",
+ status: "succeeded",
+ attempts: 1,
+ lastResponseStatus: 204,
+ });
+ // A success is a success: it clears the count like any delivery.
+ expect(
+ (
+ await prisma.spaceWebhook.findUniqueOrThrow({
+ where: { id: webhook.id },
+ })
+ ).consecutiveFailures,
+ ).toBe(0);
+ } finally {
+ await receiver.stop();
+ }
+ });
+
+ test("a successful test event keeps an endpoint Rallly turned off marked as such", async ({
+ page,
+ }) => {
+ const receiver = await startReceiver(204);
+ try {
+ const { space, email } = await createOwner("webhooks-test-off", {
+ pro: true,
+ });
+ const webhook = await createWebhookInDb({
+ spaceId: space.id,
+ url: receiver.url,
+ enabled: false,
+ consecutiveFailures: MAX_CONSECUTIVE_FAILURES,
+ });
+
+ await gotoWebhooks(page, email);
+
+ await endpointRow(page, receiver.url)
+ .getByRole("button", { name: "More options" })
+ .click();
+ await page.getByRole("menuitem", { name: "Send test event" }).click();
+ await expect(page.getByText("Test event delivered")).toBeVisible();
+
+ // The count is what tells a dispatcher disable from an owner disable,
+ // so only turning the endpoint back on clears it.
+ const after = await prisma.spaceWebhook.findUniqueOrThrow({
+ where: { id: webhook.id },
+ });
+ expect(after.enabled).toBe(false);
+ expect(after.consecutiveFailures).toBe(MAX_CONSECUTIVE_FAILURES);
+ await expect(
+ endpointRow(page, receiver.url).getByRole("button", {
+ name: "Turned off after failures",
+ }),
+ ).toBeVisible();
+ } finally {
+ await receiver.stop();
+ }
+ });
+
+ test("a failed test event does not count against the endpoint", async ({
+ page,
+ }) => {
+ const receiver = await startReceiver(503);
+ try {
+ const { space, email } = await createOwner("webhooks-test-fail", {
+ pro: true,
+ });
+ // One exhausted event short of being turned off: a test must not be
+ // what tips it over.
+ const webhook = await createWebhookInDb({
+ spaceId: space.id,
+ url: receiver.url,
+ consecutiveFailures: MAX_CONSECUTIVE_FAILURES - 1,
+ });
+
+ await gotoWebhooks(page, email);
+
+ await endpointRow(page, receiver.url)
+ .getByRole("button", { name: "More options" })
+ .click();
+ await page.getByRole("menuitem", { name: "Send test event" }).click();
+
+ await expect(page.getByText("Test event failed")).toBeVisible();
+ expect(receiver.requests).toHaveLength(1);
+
+ const after = await prisma.spaceWebhook.findUniqueOrThrow({
+ where: { id: webhook.id },
+ });
+ expect(after.enabled).toBe(true);
+ expect(after.consecutiveFailures).toBe(MAX_CONSECUTIVE_FAILURES - 1);
+
+ // Recorded as exhausted, never as a failure awaiting retry, so the
+ // dispatcher leaves it alone.
+ const delivery = await prisma.webhookDelivery.findFirstOrThrow({
+ where: { webhookId: webhook.id },
+ });
+ expect(delivery).toMatchObject({
+ eventType: "ping",
+ status: "exhausted",
+ lastResponseStatus: 503,
+ lastError: "HTTP 503",
+ });
+
+ await expect(
+ endpointRow(page, receiver.url).getByRole("button", {
+ name: "Failing",
+ }),
+ ).toBeVisible();
+ } finally {
+ await receiver.stop();
+ }
});
test("a member of the space cannot reach the page", async ({ page }) => {