feat(webhooks): key-template fallback operator + provider handshake hook

Two provider-agnostic engine capabilities the Slack channel needs, kept generic so any provider reuses them:

- Session key templates gain a first-non-empty fallback: {a || b || c} resolves to the first non-empty path. A Slack message that STARTS a thread has no thread_ts (only replies do), so the natural key {body.team_id}:{body.event.channel}:{body.event.thread_ts || body.event.ts} would otherwise drop the first message of every conversation. Implemented in both the runtime evaluator and the type-level key validator.

- A generic handshake hook on the verifier artifact: a signed request whose body matches a declared { matchPath, matchValue } is echoed synchronously (the respondPath value, 200) and NOT recorded or routed. Covers Slack url_verification and Discord PING. ingest() consults it after verify, before the front gate.

Unreleased feature, so no released-API impact.

Author: ericallam

apps/webapp/app/routes/webhooks.v1.ingest.$opaqueId.ts

@@ -54,6 +54,9 @@ export async function action({ request, params }: ActionFunctionArgs) {
     case "accepted":
       logger.info("webhook ingress accepted", { opaqueId, deliveryId: result.deliveryId });
       return json({ received: true, deliveryId: result.deliveryFriendlyId }, { status: 200 });
+    case "handshake":
+      // Provider handshake echo (e.g. Slack url_verification): the challenge value, plain text, 200.
+      return new Response(result.body, { status: 200, headers: { "content-type": "text/plain" } });
     case "duplicate":
       return json({ received: true, deliveryId: result.deliveryId }, { status: 200 });
     case "endpoint_not_found":

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

@@ -28,7 +28,7 @@ import {
   WebhookDeliverTaskErrorType,
   WebhookEngineOptions,
 } from "./types.js";
-import { evaluateSessionKeyTemplate } from "./sessionKey.js";
+import { evaluateSessionKeyTemplate, walkPath as resolveBodyPath } from "./sessionKey.js";
 
 // The deliver job's retry budget (redis-worker DLQs after this many attempts).
 const WEBHOOK_DELIVER_MAX_ATTEMPTS = webhookWorkerCatalog["webhook.deliver"].retry.maxAttempts;
@@ -164,6 +164,17 @@ export class WebhookEngine {
         return { outcome: "verification_failed", error: verdict.error ?? "invalid" };
       }
 
+      // Provider handshake (Slack url_verification, Discord PING): a signed request that must get a
+      // synchronous echo, not a recorded/routed delivery. Generic, declared on the verifier artifact.
+      const handshake =
+        "handshake" in parsedArtifact.data ? parsedArtifact.data.handshake : undefined;
+      if (handshake) {
+        const event = verdict.parsedEvent as unknown;
+        if (String(resolveBodyPath(event, handshake.matchPath) ?? "") === handshake.matchValue) {
+          return { outcome: "handshake", body: String(resolveBodyPath(event, handshake.respondPath) ?? "") };
+        }
+      }
+
       // If the scheme carries its secret in a custom header, don't persist that header (auth/cookie
       // are dropped unconditionally). Verification above already ran against the full header set.
       const secretHeader =

internal-packages/webhook-engine/src/engine/ingest.test.ts

@@ -199,6 +199,56 @@ containerTestWithIsolatedRedisNoClickhouse(
   }
 );
 
+containerTestWithIsolatedRedisNoClickhouse(
+  "a provider handshake (url_verification) echoes the challenge and records no delivery",
+  async ({ prisma, redisOptions }) => {
+    const endpoint = await prisma.webhookEndpoint.create({
+      data: {
+        friendlyId: WebhookEndpointId.generate().friendlyId,
+        opaqueId: `op_${randomBytes(12).toString("hex")}`,
+        organizationId: "org_test",
+        projectId: "proj_test",
+        runtimeEnvironmentId: "env_test",
+        environmentType: "PRODUCTION",
+        source: "slack",
+        handlerWebhookId: "handle-slack-channel",
+        routingTarget: { type: "task", taskId: "unused" },
+        verifierArtifact: {
+          kind: "config",
+          config: VERIFIER_CONFIG,
+          handshake: { matchPath: "type", matchValue: "url_verification", respondPath: "challenge" },
+        },
+        signingSecretKey: SECRET_KEY,
+        status: "ACTIVE",
+      },
+    });
+    const { triggerTask } = makeTriggerTaskStub();
+    const engine = buildEngine(prisma, redisOptions, triggerTask);
+
+    try {
+      const body = JSON.stringify({ type: "url_verification", challenge: "chal_xyz" });
+      const t = Math.floor(Date.now() / 1000);
+      const sig = createHmac("sha256", SECRET).update(`${t}.${body}`).digest("hex");
+      const result = await engine.ingest({
+        opaqueId: endpoint.opaqueId,
+        rawBytes: new TextEncoder().encode(body),
+        headers: { "stripe-signature": `t=${t},v1=${sig}` },
+        url: `https://api.example.com/webhooks/v1/ingest/${endpoint.opaqueId}`,
+      });
+
+      expect(result.outcome).toBe("handshake");
+      if (result.outcome === "handshake") expect(result.body).toBe("chal_xyz");
+
+      const count = await prisma.webhookDelivery.count({
+        where: { webhookEndpointId: endpoint.id },
+      });
+      expect(count).toBe(0);
+    } finally {
+      await engine.quit();
+    }
+  }
+);
+
 containerTestWithIsolatedRedisNoClickhouse(
   "concurrent duplicate deliveries collapse to one delivery row and one run",
   async ({ prisma, redisOptions }) => {

internal-packages/webhook-engine/src/engine/sessionKey.test.ts

@@ -64,4 +64,19 @@ describe("evaluateSessionKeyTemplate", () => {
   it("coerces numbers and booleans (including 0/false) to strings", () => {
     expect(evaluateSessionKeyTemplate("{body.n}-{body.b}", ns({ n: 0, b: false }))).toBe("0-false");
   });
+
+  it("falls back to the next path with || when the first is empty (Slack thread_ts || ts)", () => {
+    const template = "{body.channel}:{body.thread_ts || body.ts}";
+    // reply: thread_ts present -> used
+    expect(
+      evaluateSessionKeyTemplate(template, ns({ channel: "C1", thread_ts: "t1", ts: "m2" }))
+    ).toBe("C1:t1");
+    // thread start: no thread_ts -> falls back to ts
+    expect(evaluateSessionKeyTemplate(template, ns({ channel: "C1", ts: "m2" }))).toBe("C1:m2");
+  });
+
+  it("uses the first non-empty across a || chain, else undefined", () => {
+    expect(evaluateSessionKeyTemplate("{body.a || body.b || body.c}", ns({ c: "z" }))).toBe("z");
+    expect(evaluateSessionKeyTemplate("{body.a || body.b}", ns({}))).toBeUndefined();
+  });
 });

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

@@ -15,12 +15,14 @@ export function evaluateSessionKeyTemplate(
 ): string | undefined {
   let ok = true;
   const out = template.replace(/\{([^}]+)\}/g, (_match, raw: string) => {
-    const value = resolveKeyPath(raw, ns);
-    if (value === undefined || value === null || value === "") {
-      ok = false;
-      return "";
+    // A placeholder may list fallbacks: `{a || b || c}` resolves to the first non-empty path (so a
+    // Slack thread-start with no thread_ts falls back to ts). Missing/empty everywhere fails the key.
+    for (const path of raw.split("||")) {
+      const value = resolveKeyPath(path.trim(), ns);
+      if (value !== undefined && value !== null && value !== "") return String(value);
     }
-    return String(value);
+    ok = false;
+    return "";
   });
   return ok ? out : undefined;
 }
@@ -41,7 +43,8 @@ function resolveKeyPath(path: string, ns: SessionKeyNamespaces): unknown {
   return walkPath(ns.body, dotted);
 }
 
-function walkPath(root: unknown, dotted: string): unknown {
+// Resolve a dotted path over an arbitrary object (shared with the ingest handshake hook).
+export function walkPath(root: unknown, dotted: string): unknown {
   let current: unknown = root;
   for (const segment of dotted.split(".")) {
     if (current === null || typeof current !== "object") return undefined;

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

@@ -96,6 +96,7 @@ export type ReplayResult =
 
 export type IngestResult =
   | { outcome: "accepted"; deliveryId: string; deliveryFriendlyId: string }
+  | { outcome: "handshake"; body: string } // provider handshake (Slack url_verification) -> 200 echo
   | { outcome: "duplicate"; deliveryId: string } // front-gate hit -> 200
   | { outcome: "endpoint_not_found" } // -> 404
   | { outcome: "endpoint_inactive" } // -> 404

packages/core/src/v3/schemas/webhookConfig.ts

@@ -129,10 +129,29 @@ export const WebhookVerifierConfig = z.discriminatedUnion("scheme", [
 ]);
 export type WebhookVerifierConfig = z.infer<typeof WebhookVerifierConfig>;
 
+// ── Provider handshake: a signed request that must get a synchronous echo, not a recorded/routed
+// delivery (Slack url_verification, Discord PING). Generic + data-only: if the verified body's
+// `matchPath` equals `matchValue`, ingest responds 200 with the body's `respondPath` value. ──
+export const WebhookHandshakeConfig = z.object({
+  matchPath: z.string(), // dotted path into the body, e.g. "type"
+  matchValue: z.string(), // e.g. "url_verification"
+  respondPath: z.string(), // dotted path to echo, e.g. "challenge"
+});
+export type WebhookHandshakeConfig = z.infer<typeof WebhookHandshakeConfig>;
+
 // ── Verifier artifact: data-only tagged union stored on WebhookEndpoint.verifierArtifact ──
 export const WebhookVerifierArtifact = z.discriminatedUnion("kind", [
-  z.object({ kind: z.literal("config"), config: WebhookVerifierConfig }),
-  z.object({ kind: z.literal("preset"), preset: z.string(), config: WebhookVerifierConfig }),
+  z.object({
+    kind: z.literal("config"),
+    config: WebhookVerifierConfig,
+    handshake: WebhookHandshakeConfig.optional(),
+  }),
+  z.object({
+    kind: z.literal("preset"),
+    preset: z.string(),
+    config: WebhookVerifierConfig,
+    handshake: WebhookHandshakeConfig.optional(),
+  }),
   z.object({ kind: z.literal("bundle"), bundleUrl: z.string(), hash: z.string() }), // P3 seam
 ]);
 export type WebhookVerifierArtifact = z.infer<typeof WebhookVerifierArtifact>;

packages/core/src/v3/types/chatEvents.ts

@@ -29,9 +29,15 @@ type PathValue<T, P extends string> = P extends `${infer Head}.${infer Rest}`
 
 export type WebhookKeyError<M extends string> = `✖ ${M}`;
 
+type TrimSpace<S extends string> = S extends ` ${infer R}`
+  ? TrimSpace<R>
+  : S extends `${infer L} `
+    ? TrimSpace<L>
+    : S;
+
 // Validate one {…} placeholder by namespace: webhook.→WebhookKeyMeta, header.→any non-empty name,
 // body./bare→event. `true` when a scalar path, else a branded error naming it.
-type CheckKeyPath<TEvent, Path extends string> = Path extends `webhook.${infer Rest}`
+type CheckKeyPathSingle<TEvent, Path extends string> = Path extends `webhook.${infer Rest}`
   ? PathValue<WebhookKeyMeta, Rest> extends WebhookKeyScalar
     ? true
     : WebhookKeyError<`unknown or non-scalar webhook meta path: ${Rest}`>
@@ -47,6 +53,13 @@ type CheckKeyPath<TEvent, Path extends string> = Path extends `webhook.${infer R
         ? true
         : WebhookKeyError<`unknown or non-scalar event path: ${Path}`>;
 
+// A placeholder may list first-non-empty fallbacks: `{a || b}`. Validate each side as a path.
+type CheckKeyPath<TEvent, Path extends string> = Path extends `${infer L}||${infer R}`
+  ? CheckKeyPathSingle<TEvent, TrimSpace<L>> extends true
+    ? CheckKeyPath<TEvent, TrimSpace<R>>
+    : CheckKeyPathSingle<TEvent, TrimSpace<L>>
+  : CheckKeyPathSingle<TEvent, TrimSpace<Path>>;
+
 type CheckKeyTemplate<TEvent, S extends string> = S extends `${infer _Pre}{${infer Path}}${infer Rest}`
   ? CheckKeyPath<TEvent, Path> extends true
     ? CheckKeyTemplate<TEvent, Rest>