perf(webapp,core): time-encode webhook delivery ids to prune the detail lookup

The delivery detail point lookup queried WebhookDelivery by id and environment
only. The table is RANGE-partitioned on createdAt, so with no createdAt
predicate Postgres cannot prune and probes every daily partition.

The delivery id now embeds its mint timestamp (a 6-byte big-endian unix ms
prefix plus random bytes, base32hex encoded), and the engine stores that same
timestamp as the row's createdAt, so the id's timestamp is the partition key.
getDelivery recovers it from the friendlyId and adds it as an exact predicate,
pruning to the row's partition for every caller. A legacy id that does not
decode falls back to the unpruned lookup.

Author: ericallam

apps/webapp/app/services/webhookDeliveriesRepository/clickhouseWebhookDeliveriesRepository.server.ts

@@ -1,4 +1,5 @@
 import { type ClickhouseQueryBuilder } from "@internal/clickhouse";
+import { WebhookDeliveryId } from "@trigger.dev/core/v3/isomorphic";
 import { boundedIn } from "@trigger.dev/database";
 import { decodeRunsCursor, encodeRunsCursor } from "../runsRepository/runsCursor.server";
 import {
@@ -281,14 +282,23 @@ export class ClickHouseWebhookDeliveriesRepository implements IWebhookDeliveries
    * A point lookup: pure Postgres, never ClickHouse. `friendlyId` is `whd_` + the row id, so we
    * strip the prefix and hit the composite-PK index (scoped by environment). ClickHouse is for
    * aggregations and for filtering/ordering a list into ids, never for selecting a row's columns.
+   *
+   * `WebhookDelivery` is RANGE-partitioned on `createdAt`, so a bare `id` predicate can't prune and
+   * probes every partition. The delivery id is time-encoded (see `WebhookDeliveryId`) with the same
+   * timestamp the engine stores as `createdAt`, so we recover it from the id and add it as an exact
+   * predicate to prune to the row's partition. A legacy id that doesn't decode falls back to the
+   * unpruned lookup.
    */
   async getDelivery(options: GetWebhookDeliveryOptions): Promise<DetailedWebhookDelivery | null> {
-    const id = options.friendlyId.startsWith(WEBHOOK_DELIVERY_ID_PREFIX)
-      ? options.friendlyId.slice(WEBHOOK_DELIVERY_ID_PREFIX.length)
-      : options.friendlyId;
+    const id = WebhookDeliveryId.toId(options.friendlyId);
+    const createdAt = WebhookDeliveryId.parseTimestamp(options.friendlyId);
 
     return this.options.prisma.webhookDelivery.findFirst({
-      where: { id, runtimeEnvironmentId: options.environmentId },
+      where: {
+        id,
+        runtimeEnvironmentId: options.environmentId,
+        ...(createdAt ? { createdAt } : {}),
+      },
       select: DELIVERY_DETAIL_SELECT,
     });
   }

internal-packages/webhook-engine/src/engine/index.ts

@@ -229,8 +229,7 @@ export class WebhookEngine {
         : undefined;
 
     const gateKey = `webhookdedupe:${endpoint.id}:${idempotencyKey}`;
-    const { id, friendlyId } = WebhookDeliveryId.generate();
-    const createdAt = new Date();
+    const { id, friendlyId, timestamp: createdAt } = WebhookDeliveryId.generate();
 
     const claimed = await this.frontGate.set(
       gateKey,
@@ -377,8 +376,7 @@ export class WebhookEngine {
         return { outcome: "unsupported_target" };
       }
 
-      const { id, friendlyId } = WebhookDeliveryId.generate();
-      const createdAt = new Date();
+      const { id, friendlyId, timestamp: createdAt } = WebhookDeliveryId.generate();
 
       await this.prisma.webhookDelivery.create({
         data: {

packages/core/src/v3/isomorphic/friendlyId.test.ts

@@ -4,6 +4,7 @@ import {
   WaitpointId,
   SnapshotId,
   QueueId,
+  WebhookDeliveryId,
   RUN_OPS_ID_LENGTH,
   RUN_OPS_ID_REGION_INDEX,
   RUN_OPS_ID_VERSION,
@@ -201,3 +202,51 @@ describe("firekeeper pod-name round-trip (runner-<id>[-attempt-N] → run_<id>)"
     expect(podName.length).toBeLessThanOrEqual(63);
   });
 });
+
+describe("WebhookDeliveryId (time-encoded)", () => {
+  it("generate() round-trips and parseTimestamp recovers the exact mint timestamp", () => {
+    const { id, friendlyId, timestamp } = WebhookDeliveryId.generate();
+
+    expect(friendlyId).toBe(`whd_${id}`);
+    expect(id.length).toBe(25);
+    expect(WebhookDeliveryId.toId(friendlyId)).toBe(id);
+    expect(WebhookDeliveryId.toId(id)).toBe(id);
+    expect(WebhookDeliveryId.toFriendlyId(id)).toBe(friendlyId);
+    expect(WebhookDeliveryId.parseTimestamp(friendlyId)?.getTime()).toBe(timestamp.getTime());
+    expect(WebhookDeliveryId.parseTimestamp(id)?.getTime()).toBe(timestamp.getTime());
+  });
+
+  it("encodes the wall-clock mint time so the partition key is recoverable", () => {
+    vi.useFakeTimers();
+    try {
+      const minted = new Date("2026-08-09T12:34:56.789Z");
+      vi.setSystemTime(minted);
+      const { friendlyId, timestamp } = WebhookDeliveryId.generate();
+      expect(timestamp.getTime()).toBe(minted.getTime());
+      expect(WebhookDeliveryId.parseTimestamp(friendlyId)?.toISOString()).toBe(
+        "2026-08-09T12:34:56.789Z"
+      );
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("sorts lexicographically in mint order at millisecond resolution", () => {
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(new Date("2026-08-09T00:00:00.000Z"));
+      const first = WebhookDeliveryId.generate().id;
+      vi.setSystemTime(new Date("2026-08-09T00:00:00.001Z"));
+      const second = WebhookDeliveryId.generate().id;
+      expect(first < second).toBe(true);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("returns undefined for legacy or malformed ids so callers skip pruning", () => {
+    expect(WebhookDeliveryId.parseTimestamp("whd_tooShort")).toBeUndefined();
+    expect(WebhookDeliveryId.parseTimestamp(`whd_${"z".repeat(24)}1`)).toBeUndefined();
+    expect(WebhookDeliveryId.parseTimestamp(`whd_${"0".repeat(24)}9`)).toBeUndefined();
+  });
+});

packages/core/src/v3/isomorphic/friendlyId.ts

@@ -268,7 +268,77 @@ export const AttemptId = new IdUtil("attempt");
 export const ErrorId = new IdUtil("error");
 export const SessionId = new IdUtil("session");
 export const WebhookEndpointId = new IdUtil("wh"); // wh_...
-export const WebhookDeliveryId = new IdUtil("whd"); // whd_...
+
+/**
+ * Webhook delivery id: time-encoded so the partition key (`createdAt`) is recoverable from the id.
+ * The body is `base32hex(6-byte big-endian unix ms timestamp + 9 CSPRNG bytes)` (24 chars) plus a
+ * version char "1", prefixed `whd_`. `WebhookDelivery` is RANGE-partitioned on `createdAt`, and the
+ * engine sets the row's `createdAt` to the mint timestamp, so a point lookup by id can recover the
+ * partition from the id alone instead of threading `createdAt` through every caller. Legacy (cuid)
+ * ids decode to `undefined` so callers fall back to an unpruned lookup.
+ */
+const WEBHOOK_DELIVERY_ID_PREFIX = "whd";
+const WEBHOOK_DELIVERY_ID_TIMESTAMP_BYTES = 6;
+const WEBHOOK_DELIVERY_ID_CORE_BYTES = 15;
+const WEBHOOK_DELIVERY_ID_CORE_LENGTH = 24;
+const WEBHOOK_DELIVERY_ID_VERSION = "1";
+const WEBHOOK_DELIVERY_ID_BODY_LENGTH = 25;
+
+function webhookDeliveryIdBody(idOrFriendlyId: string): string {
+  return idOrFriendlyId.startsWith(`${WEBHOOK_DELIVERY_ID_PREFIX}_`)
+    ? idOrFriendlyId.slice(WEBHOOK_DELIVERY_ID_PREFIX.length + 1)
+    : idOrFriendlyId;
+}
+
+export const WebhookDeliveryId = {
+  /**
+   * Mint a delivery id. The row's `createdAt` MUST be set to the returned `timestamp` so the id's
+   * embedded timestamp equals the partition key that {@link WebhookDeliveryId.parseTimestamp} recovers.
+   */
+  generate(): { id: string; friendlyId: string; timestamp: Date } {
+    const timestamp = new Date();
+    const core = new Uint8Array(WEBHOOK_DELIVERY_ID_CORE_BYTES);
+    let ms = timestamp.getTime();
+    for (let i = WEBHOOK_DELIVERY_ID_TIMESTAMP_BYTES - 1; i >= 0; i--) {
+      core[i] = ms % 256;
+      ms = Math.floor(ms / 256);
+    }
+    getRandomValues(core.subarray(WEBHOOK_DELIVERY_ID_TIMESTAMP_BYTES));
+    const id = `${base32hexEncode(core)}${WEBHOOK_DELIVERY_ID_VERSION}`;
+    return { id, friendlyId: `${WEBHOOK_DELIVERY_ID_PREFIX}_${id}`, timestamp };
+  },
+
+  toFriendlyId(id: string): string {
+    return id.startsWith(`${WEBHOOK_DELIVERY_ID_PREFIX}_`)
+      ? id
+      : `${WEBHOOK_DELIVERY_ID_PREFIX}_${id}`;
+  },
+
+  toId(idOrFriendlyId: string): string {
+    return webhookDeliveryIdBody(idOrFriendlyId);
+  },
+
+  /**
+   * Decode the mint timestamp (== the row's `createdAt` partition key) from a v1 id or friendlyId.
+   * Returns `undefined` for a legacy (cuid) id, which signals the caller to skip partition pruning.
+   */
+  parseTimestamp(idOrFriendlyId: string): Date | undefined {
+    const body = webhookDeliveryIdBody(idOrFriendlyId);
+    if (body.length !== WEBHOOK_DELIVERY_ID_BODY_LENGTH) return undefined;
+    if (body[WEBHOOK_DELIVERY_ID_CORE_LENGTH] !== WEBHOOK_DELIVERY_ID_VERSION) return undefined;
+    let core: Uint8Array;
+    try {
+      core = base32hexDecode(body.slice(0, WEBHOOK_DELIVERY_ID_CORE_LENGTH));
+    } catch {
+      return undefined;
+    }
+    let ms = 0;
+    for (let i = 0; i < WEBHOOK_DELIVERY_ID_TIMESTAMP_BYTES; i++) {
+      ms = ms * 256 + (core[i] ?? 0);
+    }
+    return new Date(ms);
+  },
+};
 
 export class IdGenerator {
   private alphabet: string;