feat(webhooks): accept form-encoded webhook bodies and an empty 200 acknowledgement

Hosted webhook endpoints now accept `application/x-www-form-urlencoded`
bodies. A verified form body that isn't JSON is routed as an object of
its fields, so Slack slash commands, Twilio and other form-posting
providers reach `webhook()` subscribers, agent session routes and
waiters like any JSON event:

```ts
export const miphy = webhook({
  id: "miphy-command",
  endpoint: slackCommands,
  filter: "event.command == '/miphy'",
  onEvent: async ({ event }) => {
    // event = { command: "/miphy", text: "a raccoon dancing", user_id: "U...", response_url: "...", ... }
  },
});
```

A repeated field becomes an array. A source's `formPayload` field (Slack
interactivity's `payload=<json>`) still takes precedence, and
verification is unchanged because it runs over the raw bytes first.

A source's response contract can also set `acceptedBody: "empty"` to
acknowledge with an empty 200 instead of the JSON receipt, for providers
such as Slack that show a non-empty reply to the user.

Mono-RevId: 8ab4361a8ae1e4ae19c029d41929ab6b26a03fb8

Author: ericallam

apps/webapp/app/v3/webhookIngressResponse.server.ts

@@ -1,4 +1,5 @@
 import type { IngestResult } from "@internal/webhook-engine";
+import type { WebhookResponseConfig } from "@trigger.dev/core/v3";
 
 /** What the public ingress answers a provider with for one ingest outcome. */
 export type WebhookHttpResponse = {
@@ -12,15 +13,15 @@ export type WebhookHttpResponse = {
 /**
  * Map an ingest outcome to the HTTP answer the provider sees. Defaults are 200 JSON on success and
  * 400 on missing credentials or a bad signature; an endpoint whose verifier artifact declares a
- * response contract (`acceptedStatus`, `rejectedStatus`) or handshake status gets those instead. The dashboard
+ * response contract (`acceptedStatus`, `acceptedBody`, `rejectedStatus`) or handshake status gets those instead. The dashboard
  * test-send reports the same status and body inside its own result envelope.
  */
 export function webhookHttpResponseFor(result: IngestResult): WebhookHttpResponse {
   switch (result.outcome) {
     case "accepted":
-      return acceptedResponse(result.response?.acceptedStatus ?? 200, result.deliveryFriendlyId);
+      return acceptedResponse(result.response, result.deliveryFriendlyId);
     case "duplicate":
-      return acceptedResponse(result.response?.acceptedStatus ?? 200, result.deliveryId);
+      return acceptedResponse(result.response, result.deliveryId);
     case "handshake":
       return {
         status: result.status,
@@ -57,10 +58,16 @@ export function webhookHttpResponseFor(result: IngestResult): WebhookHttpRespons
   }
 }
 
-function acceptedResponse(status: 200 | 202 | 204, deliveryId: string | undefined) {
+function acceptedResponse(
+  contract: WebhookResponseConfig | undefined,
+  deliveryId: string | undefined
+): WebhookHttpResponse {
+  const status = contract?.acceptedStatus ?? 200;
+  if (status === 204) return { status, body: null, contentType: "application/json" };
+  if (contract?.acceptedBody === "empty") return { status, body: "", contentType: "text/plain" };
   return {
     status,
-    body: status === 204 ? null : JSON.stringify({ received: true, deliveryId }),
+    body: JSON.stringify({ received: true, deliveryId }),
     contentType: "application/json",
   };
 }

apps/webapp/test/webhookIngressResponse.test.ts

@@ -34,6 +34,27 @@ describe("webhook ingress HTTP contract", () => {
     expect(await res.text()).toBe("");
   });
 
+  it("acknowledges accepted and duplicate deliveries with an empty 200 when the contract asks for no body", async () => {
+    for (const result of [
+      {
+        outcome: "accepted" as const,
+        deliveryId: "d_1",
+        deliveryFriendlyId: "whdel_1",
+        response: { acceptedBody: "empty" as const },
+      },
+      {
+        outcome: "duplicate" as const,
+        deliveryId: "whdel_1",
+        response: { acceptedBody: "empty" as const },
+      },
+    ]) {
+      const res = toWebhookHttpResponse(webhookHttpResponseFor(result));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("text/plain");
+      expect(await res.text()).toBe("");
+    }
+  });
+
   it("keeps the default 200 JSON acknowledgement when no contract is declared", async () => {
     const res = toWebhookHttpResponse(
       webhookHttpResponseFor({

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

@@ -31,7 +31,7 @@ import { type CachedEndpoint, TtlCache } from "./cache.js";
 import { evaluateFilter, parseFilter } from "./filter/index.js";
 import { verify } from "./verification/index.js";
 import { sha256Hex } from "./verification/util.js";
-import { deriveIdempotencyKey, tryParseJson } from "./verification/derive.js";
+import { deriveIdempotencyKey, parseEventBody } from "./verification/derive.js";
 import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import type {
   CancelWebhookWaiterResult,
@@ -616,8 +616,8 @@ export class WebhookEngine {
   /**
    * Inject a delivery WITHOUT signature verification, then run the same filter + record + route path
    * as ingest(). This is the test-console "simulate" mode for endpoints we cannot sign for
-   * (asymmetric public-key schemes; url-secret path placement). The body must be JSON. Everything
-   * downstream (filter, startOn, routing, run/session) runs for real.
+   * (asymmetric public-key schemes; url-secret path placement). The body must be JSON, or a form
+   * sent with a form-encoded content type. Everything downstream (filter, startOn, routing, run/session) runs for real.
    */
   async simulateInject(input: IngestInput): Promise<IngestResult> {
     this.#assertEnabled();
@@ -635,7 +635,7 @@ export class WebhookEngine {
         return { outcome: "verification_failed", error: "corrupt verifier artifact" };
       }
 
-      const parsed = tryParseJson(input.rawBytes);
+      const parsed = parseEventBody(input.rawBytes, { headers: input.headers });
       if (parsed.error || parsed.parsedEvent === undefined) {
         return {
           outcome: "verification_failed",

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

@@ -865,6 +865,109 @@ containerTestWithIsolatedRedisNoClickhouse(
   }
 );
 
+containerTestWithIsolatedRedisNoClickhouse(
+  "a form-encoded body routes as the decoded form to a filtered task and a session keyed on its fields",
+  async ({ prisma, redisOptions }) => {
+    const filter = "event.command == '/miphy'";
+    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",
+        declaredId: "slack-commands",
+        routingTargets: [
+          {
+            type: "task",
+            id: "miphy-command",
+            taskId: "miphy-command",
+            filter,
+            filterAst: parseFilter(filter) as unknown as Prisma.InputJsonValue,
+            filterAstVersion: 1,
+          },
+          {
+            type: "task",
+            id: "other-command",
+            taskId: "other-command",
+            filter: "event.command == '/other'",
+            filterAst: parseFilter("event.command == '/other'") as unknown as Prisma.InputJsonValue,
+            filterAstVersion: 1,
+          },
+          {
+            type: "session",
+            id: "agent-x:commands",
+            taskIdentifier: "agent-x",
+            keyTemplate: "{body.channel_id}:{body.user_id}",
+            actionType: "slash.command",
+            deliverAs: "action",
+          },
+        ],
+        verifierArtifact: { kind: "config", config: VERIFIER_CONFIG },
+        signingSecretKey: SECRET_KEY,
+        status: "ACTIVE",
+      },
+    });
+    const { triggerTask, calls } = makeTriggerTaskStub();
+    const sessions = makeDeliverToSessionStub();
+    const engine = buildEngine(prisma, redisOptions, triggerTask, {
+      deliverToSession: sessions.deliverToSession,
+    });
+
+    try {
+      const body =
+        "team_id=T1&channel_id=C1&user_id=U1&command=%2Fmiphy&text=a+raccoon+dancing&trigger_id=13.4";
+      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}`,
+          "content-type": "application/x-www-form-urlencoded",
+        },
+        url: `https://api.example.com/webhooks/v1/ingest/${endpoint.opaqueId}`,
+      });
+      if (result.outcome !== "accepted")
+        throw new Error(`expected accepted, got ${result.outcome}`);
+
+      await waitFor(async () => {
+        const d = await prisma.webhookDelivery.findFirst({ where: { id: result.deliveryId } });
+        return d?.status === "SUCCEEDED";
+      });
+
+      const event = {
+        team_id: "T1",
+        channel_id: "C1",
+        user_id: "U1",
+        command: "/miphy",
+        text: "a raccoon dancing",
+        trigger_id: "13.4",
+      };
+      const delivery = await prisma.webhookDelivery.findFirst({ where: { id: result.deliveryId } });
+      expect(delivery?.errorMessage).toBeNull();
+      expect(delivery?.parsedEvent).toEqual(event);
+      const targets = (delivery?.targets ?? []) as Array<{ id: string; status: string }>;
+      expect(targets.map((t) => [t.id, t.status])).toEqual([
+        ["miphy-command", "SUCCEEDED"],
+        ["other-command", "FILTERED"],
+        ["agent-x:commands", "SUCCEEDED"],
+      ]);
+
+      expect(calls).toHaveLength(1);
+      expect(calls[0]?.taskId).toBe("miphy-command");
+      expect(calls[0]?.payload).toEqual(event);
+      expect(sessions.calls).toHaveLength(1);
+      expect(sessions.calls[0]?.externalId).toBe("C1:U1");
+      expect(sessions.calls[0]?.event).toEqual(event);
+    } finally {
+      await engine.quit();
+    }
+  }
+);
+
 containerTestWithIsolatedRedisNoClickhouse(
   "session delivery with an unresolvable key is FAILED and never calls the port",
   async ({ prisma, redisOptions }) => {

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

@@ -6,7 +6,7 @@ import type {
   WebhookVerifierConfig,
 } from "@trigger.dev/core/v3";
 import { randomUUID } from "node:crypto";
-import { readPath, tryParseJson } from "../verification/derive.js";
+import { isFormEncoded, parseEventBody, readPath } from "../verification/derive.js";
 import { buildSigningBytes, deriveHmacKey, hmacDigest } from "../verification/util.js";
 
 export type SignResult =
@@ -72,7 +72,9 @@ function readStringSource(
     case "constant":
       return source.value;
     case "body": {
-      const parsed = tryParseJson(args.rawBody).parsedEvent as Record<string, unknown> | undefined;
+      const parsed = parseEventBody(args.rawBody, { headers: headersLc }).parsedEvent as
+        | Record<string, unknown>
+        | undefined;
       const v = readPath(parsed, source.path);
       return typeof v === "string" || typeof v === "number" ? String(v) : undefined;
     }
@@ -98,7 +100,7 @@ function signHmac(cfg: WebhookHmacConfig, signArgs: SignArgs): SignResult {
         headersLc[src.name.toLowerCase()] = timestampValue;
       }
     } else if (src.from === "body" && signArgs.refreshBodyTimestamp) {
-      const refreshed = withBodyTimestamp(signArgs.rawBody, src.path, nowInUnit);
+      const refreshed = withBodyTimestamp(signArgs.rawBody, src.path, nowInUnit, headersLc);
       if (refreshed) {
         args = { ...signArgs, rawBody: refreshed };
         timestampValue = String(nowInUnit);
@@ -140,15 +142,23 @@ function signHmac(cfg: WebhookHmacConfig, signArgs: SignArgs): SignResult {
 }
 
 /**
- * The body with the JSON field at `path` set to `value`, re-serialized; undefined when the body is
- * not a JSON object or the existing field is not a string/number (the caller signs it as it is).
+ * The body with the field at `path` set to `value`, re-serialized; undefined when the body is not a
+ * JSON object or the existing field is not a string/number (the caller signs it as it is). A form
+ * body (per `headersLc`) is flat, so `path` names one existing field and the body stays a form.
  */
 function withBodyTimestamp(
   rawBody: Uint8Array,
   path: string,
-  value: number
+  value: number,
+  headersLc: Record<string, string>
 ): Uint8Array | undefined {
-  const parsed = tryParseJson(rawBody).parsedEvent;
+  if (isFormEncoded(headersLc)) {
+    const form = new URLSearchParams(new TextDecoder().decode(rawBody));
+    if (!form.has(path)) return undefined;
+    form.set(path, String(value));
+    return new TextEncoder().encode(form.toString());
+  }
+  const parsed = parseEventBody(rawBody).parsedEvent;
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
   const keys = path.split(".");
   if (keys.some((key) => key === "" || UNSAFE_PATH_KEYS.has(key))) return undefined;
@@ -207,7 +217,13 @@ function signSharedSecret(cfg: WebhookSharedSecretConfig, args: SignArgs): SignR
       headers["authorization"] = `Basic ${Buffer.from(`:${args.secret}`).toString("base64")}`;
       break;
     case "body": {
-      const parsed = tryParseJson(args.rawBody).parsedEvent;
+      if (isFormEncoded(headers)) {
+        const form = new URLSearchParams(new TextDecoder().decode(args.rawBody));
+        form.set(cfg.fieldName ?? "", args.secret);
+        body = new TextEncoder().encode(form.toString());
+        break;
+      }
+      const parsed = parseEventBody(args.rawBody).parsedEvent;
       if (parsed == null || typeof parsed !== "object") {
         return {
           ok: false,

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

@@ -290,6 +290,86 @@ describe("signWithVerifierConfig round-trips through the verifier", () => {
     expect({}.toString()).toBe("[object Object]");
   });
 
+  describe("form-encoded bodies", () => {
+    const FORM_HEADERS = { "Content-Type": "application/x-www-form-urlencoded" };
+    const formBody = (fields: string) => new TextEncoder().encode(fields);
+    const bodyTimestamped: WebhookHmacConfig = {
+      scheme: "hmac",
+      algorithm: "sha256",
+      encoding: "hex",
+      signatureHeader: "x-signature",
+      signature: {},
+      timestamp: { source: { from: "body", path: "ts" }, toleranceSeconds: 300 },
+      signingString: { template: "{timestamp}.{body}" },
+    };
+
+    function verifySigned(
+      config: WebhookVerifierConfig,
+      secret: string,
+      signed: ReturnType<typeof signWithVerifierConfig>
+    ) {
+      if (!signed.ok) throw new Error(`expected signable: ${signed.error}`);
+      return verify(
+        { kind: "config", config },
+        { rawBytes: signed.body, headers: signed.headers, url: signed.url, secret, nowMs: NOW }
+      );
+    }
+
+    it("signs a form field timestamp the verifier reads back", () => {
+      const secret = "form-secret";
+      const signed = signWithVerifierConfig({
+        config: bodyTimestamped,
+        secret,
+        rawBody: formBody(`ts=${NOW / 1000}&message=hello`),
+        headers: FORM_HEADERS,
+        url: INGRESS_URL,
+        nowMs: NOW,
+      });
+      const verdict = verifySigned(bodyTimestamped, secret, signed);
+      expect(verdict.ok).toBe(true);
+      expect(verdict.parsedEvent).toEqual({ ts: String(NOW / 1000), message: "hello" });
+    });
+
+    it("refreshes a stale form field timestamp and keeps the body a form", () => {
+      const secret = "form-secret";
+      const signed = signWithVerifierConfig({
+        config: bodyTimestamped,
+        secret,
+        rawBody: formBody("ts=1700000000&message=hello+there&tag=a&tag=b"),
+        headers: FORM_HEADERS,
+        url: INGRESS_URL,
+        nowMs: NOW,
+        refreshBodyTimestamp: true,
+      });
+      const verdict = verifySigned(bodyTimestamped, secret, signed);
+      expect(verdict.ok).toBe(true);
+      expect(verdict.parsedEvent).toEqual({
+        ts: String(NOW / 1000),
+        message: "hello there",
+        tag: ["a", "b"],
+      });
+    });
+
+    it("places a body shared secret into a form body", () => {
+      const config: WebhookSharedSecretConfig = {
+        scheme: "shared-secret",
+        placement: "body",
+        fieldName: "token",
+      };
+      const signed = signWithVerifierConfig({
+        config,
+        secret: "the-shared-secret",
+        rawBody: formBody("command=%2Fmiphy&text=hi"),
+        headers: FORM_HEADERS,
+        url: INGRESS_URL,
+        nowMs: NOW,
+      });
+      const verdict = verifySigned(config, "the-shared-secret", signed);
+      expect(verdict.ok).toBe(true);
+      expect(verdict.parsedEvent).toMatchObject({ command: "/miphy", text: "hi" });
+    });
+  });
+
   it("url-secret query verifies", () => {
     const config: WebhookUrlSecretConfig = {
       scheme: "url-secret",

internal-packages/webhook-engine/src/engine/verification/asymmetric.ts

@@ -1,6 +1,6 @@
 import type { WebhookAsymmetricConfig as AsymmetricConfig } from "@trigger.dev/core/v3";
 import { createPublicKey, verify as cryptoVerify, type KeyObject } from "node:crypto";
-import { deriveIdempotencyKey, tryParseJson } from "./derive.js";
+import { deriveIdempotencyKey, parseEventBody } from "./derive.js";
 import { prepareSignedVerification } from "./parse.js";
 import type { SchemeVerifier, VerifierResult, VerifyInput } from "./types.js";
 import { decodeSignature } from "./util.js";
@@ -70,7 +70,11 @@ export const asymmetricVerifier: SchemeVerifier = {
       timestampValue: prep.timestampValue,
       signatureValue: prep.signatureValue,
     });
-    return { ok: true, idempotencyKey, ...tryParseJson(input.rawBytes) };
+    return {
+      ok: true,
+      idempotencyKey,
+      ...parseEventBody(input.rawBytes, { headers: input.headers }),
+    };
   },
 };