From 444dc18d9802c85f52368a8f8f5ea6cc4c9ef541 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Thu, 12 Nov 2026 20:17:16 -0600 Subject: [PATCH] fix(routines): keep webhook secrets out of chat and link the reveal page (#21253) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - An agent can add a webhook trigger to a routine, and the API response includes the webhook URL and its secret > - Paperclip redacts secrets from chat output, so a secret that an agent writes in a reply reaches the person as `[REDACTED]` > - An agent pasted the bearer token in chat, the person saw `Authorization: Bearer [REDACTED]`, and had no way to get the key > - The person can reveal a key once on the routine's Triggers page, but the agent did not know that page > - This pull request tells the agent never to write the secret in chat and to link the Triggers page instead > - The benefit is that secrets stay out of chat and the person still gets a working key ## Linked Issues or Issue Description **What happened?** In the paid chat eval `routines.webhook-trigger`, the agent created a bearer webhook trigger. Its reasoning said the token "is sensitive; but user needs it. I'll provide it." Output redaction removed the token, so the reply showed `Authorization: Bearer [REDACTED]` and gave no secure way to get the key. **Steps to reproduce** 1. Ask an agent to add a webhook to a routine so a test service can trigger it. 2. The agent calls `POST /api/routines/{id}/triggers` and reads the secret in the response. 3. Read the agent's reply. **Expected behavior** The agent shares the webhook URL and signing mode, does not write the secret, and links the routine's Triggers page, where the person reveals the key once. ## What Changed - `server/src/routes/openapi.ts`: `POST /api/routines/{id}/triggers` and `POST /api/routine-triggers/{id}/rotate-secret` now describe the secret handling. For a signed or bearer trigger, the URL and signing mode can be shared. With `signingMode: none` the URL alone starts the routine, so it is treated as a credential too. The secret value, or a header that contains it, is never written in a chat reply, comment, document or task. The agent links `//routines//triggers`. For a trigger still awaiting setup, the link is `//routines//triggers?triggerSetup=` and the person chooses Generate new key. Otherwise the person chooses Edit webhook, then Replace key. These are the same controls the human webhook setup uses. - `server/src/__tests__/routine-webhook-secret-guidance.test.ts`: the agent API search for both operations returns this guidance. ## Verification - `cd server && npx vitest run src/__tests__/routine-webhook-secret-guidance.test.ts` passes (2 tests). The tests fail on master because the operations have no description. The tests also check the unsigned-URL rule. ## Risks - Low risk. Only agent-facing route descriptions change. Server-side redaction is unchanged. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code execution in Claude Code. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 --- .../routine-webhook-secret-guidance.test.ts | 16 ++++++++++++++++ server/src/routes/openapi.ts | 9 +++++++++ 2 files changed, 25 insertions(+) create mode 100644 server/src/__tests__/routine-webhook-secret-guidance.test.ts 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),