diff --git a/server/src/__tests__/routine-webhook-secret-guidance.test.ts b/server/src/__tests__/routine-webhook-secret-guidance.test.ts new file mode 100644 index 00000000000..8be05ec2c7c --- /dev/null +++ b/server/src/__tests__/routine-webhook-secret-guidance.test.ts @@ -0,0 +1,16 @@ +import { expect, it } from "vitest"; +import { searchRunnerApi } from "../services/native-runtime/runner-api-catalog.js"; + +it.each([ + ["routine webhook trigger", "POST /api/routines/{id}/triggers"], + ["rotate routine trigger secret", "POST /api/routine-triggers/{id}/rotate-secret"], +])("search %j tells the agent to keep the webhook secret out of chat and where the person reveals it", (query, operationId) => { + const operation = searchRunnerApi({ query, limit: 10 }).results.find(row => row.operationId === operationId); + expect(operation, query).toBeDefined(); + const description = operation!.description; + expect(description).toContain("never write its value, or a header containing it, in a chat reply"); + expect(description).toContain("//routines//triggers, as a Markdown link"); + expect(description).toContain("//routines//triggers?triggerSetup= and tell them to choose Generate new key"); + expect(description).toContain("Edit webhook, then Replace key"); + expect(description).toContain("With signingMode none the URL alone starts the routine, so treat that URL as a credential too"); +}); diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.ts index b84517ade32..643a30d7c1c 100644 --- a/server/src/routes/openapi.ts +++ b/server/src/routes/openapi.ts @@ -5548,11 +5548,19 @@ registry.registerPath({ }, }); +const ROUTINE_WEBHOOK_SECRET_GUIDANCE = "A webhook response includes secretMaterial.webhookUrl and secretMaterial.webhookSecret. " + + "The webhookSecret is a credential: never write its value, or a header containing it, in a chat reply, comment, document or task. " + + "For a signed or bearer trigger, the URL and signing mode may be shared in chat. With signingMode none the URL alone starts the routine, so treat that URL as a credential too and do not write it in chat. " + + "Instead link the person to the routine's Triggers page, //routines//triggers, as a Markdown link, where Paperclip shows a key once: " + + "for a trigger still awaiting setup, link //routines//triggers?triggerSetup= and tell them to choose Generate new key; " + + "otherwise tell them to choose Edit webhook, then Replace key. Replacing the key invalidates the earlier one."; + registry.registerPath({ method: "post", path: "/api/routines/{id}/triggers", tags: ["routines"], summary: "Create a routine trigger", + description: ROUTINE_WEBHOOK_SECRET_GUIDANCE, request: { params: z.object({ id: z.string() }), body: jsonBody(createRoutineTriggerSchema), @@ -5586,6 +5594,7 @@ registry.registerPath({ path: "/api/routine-triggers/{id}/rotate-secret", tags: ["routines"], summary: "Rotate a routine trigger secret", + description: ROUTINE_WEBHOOK_SECRET_GUIDANCE, request: { params: z.object({ id: z.string() }), body: jsonBody(rotateRoutineTriggerSecretSchema),