feat(core,cli,webapp): previousSecretTtlSeconds in the API client and MCP tools

Mono-RevId: 856c777bbc374ed4fd41275c56b00e20c5a6ea8d

Author: ericallam

.changeset/webhook-secret-grace-option.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/core": patch
+"trigger.dev": patch
+---
+
+The `generate_webhook_secret` and `set_webhook_secret` MCP tools take an optional `previousSecretTtlSeconds` to keep accepting a webhook endpoint's old signing secret while the provider switches to the new one (up to 7 days), and report when the old secret stops working.

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.webhooks.endpoints.$endpointParam/route.tsx

@@ -8,7 +8,11 @@ import {
 } from "@remix-run/react";
 import { type ActionFunctionArgs, type LoaderFunctionArgs } from "@remix-run/server-runtime";
 import { randomBytes } from "node:crypto";
-import { WebhookRoutingTarget, WebhookVerifierArtifact } from "@trigger.dev/core/v3";
+import {
+  WebhookPreviousSecretTtlSeconds,
+  WebhookRoutingTarget,
+  WebhookVerifierArtifact,
+} from "@trigger.dev/core/v3";
 import type { WebhookValueSource } from "@trigger.dev/core/v3";
 import { type MutableRefObject, Suspense, useEffect, useRef, useState } from "react";
 import { TypedAwait, typeddefer, useTypedLoaderData } from "remix-typedjson";
@@ -69,7 +73,6 @@ import { docsPath, EnvironmentParamSchema, v3WebhooksPath } from "~/utils/pathBu
 import { throwPermissionDenied } from "~/utils/permissionDenied";
 import { parseFiniteInt } from "~/utils/searchParams";
 import { webhookEngine, webhookVerifyTokenKey } from "~/v3/webhookEngine.server";
-import { PreviousSecretTtlSeconds } from "~/v3/webhookSigningSecret";
 import {
   generateWebhookSigningSecret,
   storeWebhookSigningSecret,
@@ -212,7 +215,7 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
 };
 
 const PreviousSecretTtlFormField = z.object({
-  previousSecretTtlSeconds: z.coerce.number().pipe(PreviousSecretTtlSeconds).optional(),
+  previousSecretTtlSeconds: z.coerce.number().pipe(WebhookPreviousSecretTtlSeconds).optional(),
 });
 
 const SetSecretSchema = PreviousSecretTtlFormField.extend({

apps/webapp/app/routes/api.v1.webhooks.endpoints.$endpointId.rotate-secret.ts

@@ -1,19 +1,14 @@
 import { json } from "@remix-run/server-runtime";
+import { RotateWebhookEndpointSecretRequestBody } from "@trigger.dev/core/v3";
 import { z } from "zod";
 import { webhookPrisma } from "~/db.server";
 import { webhookEndpointLookup } from "~/v3/webhookEndpointLookup";
 import { createActionApiRoute } from "~/services/routeBuilders/apiBuilder.server";
 import { safeJsonParse } from "~/utils/json";
-import { PreviousSecretTtlSeconds } from "~/v3/webhookSigningSecret";
 import { generateWebhookSigningSecret } from "~/v3/webhookSigningSecret.server";
 
 const ParamsSchema = z.object({ endpointId: z.string() });
 
-/** Optional: existing callers POST with no body, which keeps the replace-immediately behavior. */
-const RotateSecretRequestBody = z.object({
-  previousSecretTtlSeconds: PreviousSecretTtlSeconds.optional(),
-});
-
 // POST /api/v1/webhooks/endpoints/:endpointId/rotate-secret — mint a new signing secret and return
 // it ONCE. Only for schemes we generate (hmac / shared-secret); asymmetric endpoints set a public key.
 const { action, loader } = createActionApiRoute(
@@ -26,7 +21,9 @@ const { action, loader } = createActionApiRoute(
   },
   async ({ params, authentication, request }) => {
     const rawBody = await request.text();
-    const body = RotateSecretRequestBody.safeParse(rawBody ? safeJsonParse(rawBody) : {});
+    const body = RotateWebhookEndpointSecretRequestBody.safeParse(
+      rawBody ? safeJsonParse(rawBody) : {}
+    );
     if (!body.success) {
       return json({ error: "Invalid request body", issues: body.error.issues }, { status: 400 });
     }

apps/webapp/app/routes/api.v1.webhooks.endpoints.$endpointId.secret.ts

@@ -4,19 +4,14 @@ import { z } from "zod";
 import { webhookPrisma } from "~/db.server";
 import { webhookEndpointLookup } from "~/v3/webhookEndpointLookup";
 import { createActionApiRoute } from "~/services/routeBuilders/apiBuilder.server";
-import { PreviousSecretTtlSeconds } from "~/v3/webhookSigningSecret";
 import { storeWebhookSigningSecret } from "~/v3/webhookSigningSecret.server";
 
 const ParamsSchema = z.object({ endpointId: z.string() });
 
-const SetSecretRequestBody = SetWebhookEndpointSecretRequestBody.extend({
-  previousSecretTtlSeconds: PreviousSecretTtlSeconds.optional(),
-});
-
 const { action, loader } = createActionApiRoute(
   {
     params: ParamsSchema,
-    body: SetSecretRequestBody,
+    body: SetWebhookEndpointSecretRequestBody,
     method: "PUT",
     allowJWT: true,
     corsStrategy: "all",

apps/webapp/app/v3/webhookSetupPrompt.ts

@@ -152,7 +152,7 @@ export function renderWebhookSetupPrompt(
 function secretStep(endpoint: WebhookSetupPromptEndpoint, asymmetric: boolean): string {
   const source = endpoint.source;
   const replacing = endpoint.hasSigningSecret
-    ? ` ${asymmetric ? "A public key" : "A secret"} is already set; replacing it breaks deliveries until ${source} uses the new one, so only replace it when you're creating or updating the webhook in ${source}.`
+    ? ` ${asymmetric ? "A public key" : "A secret"} is already set; only replace it when you're creating or updating the webhook in ${source}, and pass \`previousSecretTtlSeconds\` (for example 3600) so deliveries signed with the old one keep verifying until ${source} uses the new one.`
     : "";
 
   if (asymmetric) {

apps/webapp/app/v3/webhookSigningSecret.ts

@@ -1,14 +1,5 @@
 import { z } from "zod";
 
-export const MAX_PREVIOUS_SECRET_TTL_SECONDS = 7 * 24 * 60 * 60;
-
-/** How long the replaced secret keeps verifying deliveries; 0 replaces it immediately. */
-export const PreviousSecretTtlSeconds = z
-  .number()
-  .int()
-  .min(0)
-  .max(MAX_PREVIOUS_SECRET_TTL_SECONDS);
-
 /**
  * An endpoint's signing secret as stored in the SecretStore. `previous` is the secret it replaced,
  * still accepted until `expiresAt` so a rotation doesn't fail deliveries the provider signs with it.

apps/webapp/test/webhookSetupPrompt.test.ts

@@ -84,7 +84,8 @@ describe("renderWebhookSetupPrompt", () => {
 
     expect(prompt).toContain("Public key: set");
     expect(prompt).toContain("Copy its public key and store it with `set_webhook_secret`.");
-    expect(prompt).toContain("A public key is already set; replacing it breaks deliveries");
+    expect(prompt).toContain("A public key is already set; only replace it when");
+    expect(prompt).toContain("pass `previousSecretTtlSeconds`");
   });
 
   it("asks which events to send when nothing subscribes yet", () => {

apps/webapp/test/webhookSigningSecret.test.ts

@@ -1,10 +1,9 @@
 import { describe, expect, it } from "vitest";
 import {
-  activeSigningSecrets,
-  MAX_PREVIOUS_SECRET_TTL_SECONDS,
-  PreviousSecretTtlSeconds,
-  replaceStoredSigningSecret,
-} from "~/v3/webhookSigningSecret";
+  MAX_WEBHOOK_PREVIOUS_SECRET_TTL_SECONDS as MAX_PREVIOUS_SECRET_TTL_SECONDS,
+  WebhookPreviousSecretTtlSeconds as PreviousSecretTtlSeconds,
+} from "@trigger.dev/core/v3";
+import { activeSigningSecrets, replaceStoredSigningSecret } from "~/v3/webhookSigningSecret";
 
 const now = new Date("2026-10-20T12:00:00.000Z");
 const later = (seconds: number) => new Date(now.getTime() + seconds * 1000);

docs/v3-openapi.yaml

@@ -4922,9 +4922,19 @@ paths:
       summary: Generate a webhook signing secret
       description: >-
         Generate a new signing secret for the endpoint, store it, and return it once. Use this for providers
-        where you choose the secret, such as GitHub. It replaces any existing secret, so deliveries fail
-        verification until the provider uses the new one. Endpoints whose source verifies with a public key
-        refuse this; set the provider's key with the set secret endpoint instead.
+        where you choose the secret, such as GitHub. It replaces the existing secret. Pass
+        `previousSecretTtlSeconds` to keep accepting the old secret while you update the provider; without
+        it, deliveries signed with the old secret fail verification straight away. Endpoints whose source
+        verifies with a public key refuse this; set the provider's key with the set secret endpoint instead.
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                previousSecretTtlSeconds:
+                  $ref: "#/components/schemas/WebhookPreviousSecretTtlSeconds"
       responses:
         "200":
           description: Successful request
@@ -4933,7 +4943,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/RotateWebhookEndpointSecretResponse"
         "400":
-          description: The endpoint's source verifies with a public key, so a secret can't be generated
+          description: The endpoint's source verifies with a public key, so a secret can't be generated, or the body is invalid
           content:
             application/json:
               schema:
@@ -4951,7 +4961,9 @@ paths:
           label: Generate a signing secret
           source: |-
             curl -X POST "https://api.trigger.dev/api/v1/webhooks/endpoints/github/rotate-secret" \
-              -H "Authorization: Bearer $TRIGGER_SECRET_KEY"
+              -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \
+              -H "Content-Type: application/json" \
+              -d '{ "previousSecretTtlSeconds": 3600 }'
   "/api/v1/webhooks/endpoints/{endpointId}/secret":
     parameters:
       - $ref: "#/components/parameters/webhookEndpointId"
@@ -4960,7 +4972,9 @@ paths:
       summary: Set a webhook signing secret
       description: >-
         Store the signing secret or public key the provider issued for this endpoint, such as the `whsec_`
-        secret Stripe returns when you create a webhook endpoint. It replaces any existing secret.
+        secret Stripe returns when you create a webhook endpoint. It replaces the existing secret. Pass
+        `previousSecretTtlSeconds` to keep accepting the old secret for a while, for example while the
+        provider rolls its secret.
       requestBody:
         required: true
         content:
@@ -4976,6 +4990,8 @@ paths:
                   maxLength: 4096
                   description: The signing secret or public key. Leading and trailing whitespace is trimmed.
                   example: whsec_5f2b...
+                previousSecretTtlSeconds:
+                  $ref: "#/components/schemas/WebhookPreviousSecretTtlSeconds"
       responses:
         "200":
           description: Successful request
@@ -5862,6 +5878,11 @@ components:
           type: string
           description: The new signing secret. It is returned only in this response and can't be read again.
           example: whsec_5f2b...
+        previousSecretExpiresAt:
+          type: string
+          format: date-time
+          description: When the replaced secret stops verifying deliveries. Absent when it was replaced immediately.
+          example: "2026-10-21T12:00:00.000Z"
     SetWebhookEndpointSecretResponse:
       type: object
       required: [id, secretSet]
@@ -5873,6 +5894,19 @@ components:
         secretSet:
           type: boolean
           const: true
+        previousSecretExpiresAt:
+          type: string
+          format: date-time
+          description: When the replaced secret stops verifying deliveries. Absent when it was replaced immediately.
+          example: "2026-10-21T12:00:00.000Z"
+    WebhookPreviousSecretTtlSeconds:
+      type: integer
+      minimum: 0
+      maximum: 604800
+      description: >-
+        How long, in seconds, the secret being replaced keeps verifying deliveries (at most 7 days). Omit it
+        or pass 0 to replace the secret immediately, for example when it leaked.
+      example: 3600
     WebhookDeliveryStatus:
       type: string
       enum: [pending, processing, succeeded, failed, filtered, unmatched]

docs/webhooks/connect.mdx

@@ -18,8 +18,8 @@ The prompt tells the agent to use the Trigger.dev MCP server (`npx trigger.dev@l
 | --- | --- |
 | `list_webhook_endpoints` | Lists the environment's endpoints, with their URL and whether a secret is set. |
 | `get_webhook_endpoint_details` | Reads one endpoint: URL, subscribers and their filters, secret state, and the setup prompt. |
-| `generate_webhook_secret` | Generates a signing secret and returns it once, for providers where you choose the secret. |
-| `set_webhook_secret` | Stores a secret the provider issued. |
+| `generate_webhook_secret` | Generates a signing secret and returns it once, for providers where you choose the secret. Optionally keeps accepting the old secret (`previousSecretTtlSeconds`). |
+| `set_webhook_secret` | Stores a secret the provider issued. Optionally keeps accepting the old secret (`previousSecretTtlSeconds`). |
 
 Without the MCP server, the same operations are available on the REST API with the environment's secret key:
 
@@ -74,7 +74,18 @@ The verify token answers the URL check. The signing secret verifies event delive
 
 Choose **Rotate signing secret** to replace a provider-supplied secret. For a secret you generate, choose **Regenerate secret**, copy the new value, and update the provider's configuration. Use **Rotate public key** when replacing an asymmetric provider's key.
 
+Both dialogs ask how long to keep accepting the old secret: **Stop immediately**, 1 hour, 24 hours (the default) or 7 days. Until then, deliveries signed with either secret verify, so you can update the provider without failing any. Choose **Stop immediately** if the old secret leaked.
+
+Through the MCP tools or the REST API, pass `previousSecretTtlSeconds` (at most 604800, 7 days). The response's `previousSecretExpiresAt` says when the old secret stops working. Without it, the old secret stops working straight away:
+
+```bash
+curl -X POST "https://api.trigger.dev/api/v1/webhooks/endpoints/github/rotate-secret" \
+  -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"previousSecretTtlSeconds": 3600}'
+```
+
 <Warning>
   Trigger.dev stores credentials encrypted and doesn't display saved values. Copy a generated secret
-  before closing the dialog. Deliveries signed with the old secret fail verification after rotation.
+  before closing the dialog.
 </Warning>