docs(workflows): document the webhook trigger (PRD-186)

[christophebrun-forest]

What

Documents the workflow webhook trigger shipped in PRD-186 (docs task tracked by PRD-616 · S11).

New pages

• reference/api/endpoints/trigger-workflow-webhook.mdx — the external HTTP contract: the webhook URL is copied from the workflow's trigger settings (not assembled from IDs, no hard-coded host), Bearer application-token auth doubling as execution identity, JSON body (record_id, composite PKs), 202 + runId, full response table (400/401/403/404/409/429), idempotency (single-run-per-record 409, no resume, retry-safe) and per-webhook rate limiting (429 + Retry-After).
• product/process/workflows/triggers.mdx — no-code page: Manual vs Webhook triggers, enabling the webhook, URL copy + token management (expiry / invalidate / regenerate), URL regeneration flow, the three revocation levers, and audit (webhook-triggered).

Updates

• docs.json — new pages added to the Workflows and Endpoints nav groups.
• reference/api/introduction.mdx — endpoint added to the endpoints table.
• product/process/workflows/overview.mdx — new "Triggering workflows" section + card.
• product/execute/workflows.mdx — mention of the webhook trigger.
• images/workflows/ — two screenshots for the no-code page.

Open points

• Endpoint host: the page makes no assumption (URL is copied from the UI). Worth confirming the real host once S5 (PRD-610) is merged, and whether it belongs under the api.forestadmin.com public-API base referenced in introduction.mdx.

🤖 Generated with Claude Code

Note

Document the workflow webhook trigger and its API endpoint

• Adds a new triggers.mdx page covering manual vs. webhook triggers, how to enable and configure the webhook, URL/token management, regeneration and revocation behavior, and auditing.
• Adds a new trigger-workflow-webhook.mdx API reference for POST <webhook_url>, documenting authentication, request body, async execution, idempotency (409), rate limiting (429), and all error statuses.
• Updates overview.mdx and workflows.mdx with brief mentions of webhook triggers and links to the new page.
• Adds a note to reference/api/introduction.mdx clarifying that the webhook endpoint does not follow the standard base URL convention.

^{Macroscope summarized 508884f.}

[linear-code]

PRD-186

PRD-616

[macroscopeapp]

🟡 Medium workflows/triggers.mdx:66

The docs say to invalidate or expire the application token "from account settings," but tokens are actually managed under Project Settings > API Access, not account settings. A user following these instructions will look in the wrong place and be unable to promptly revoke a compromised webhook token. Correct the location reference so users can find the token management UI quickly.

Suggested change

	| **Invalidate / expire the token** | Done by the token's user, from account settings. | `401` |
	| **Invalidate / expire the token** | Done by the token's user, from `Project Settings > API Access`. | `401` |

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @product/process/workflows/triggers.mdx around line 66:

The docs say to invalidate or expire the application token "from account settings," but tokens are actually managed under `Project Settings > API Access`, not account settings. A user following these instructions will look in the wrong place and be unable to promptly revoke a compromised webhook token. Correct the location reference so users can find the token management UI quickly.

[christophebrun-forest]

Dismissing this one: the workflow webhook trigger authenticates with an API token managed in Account Settings, which is a different scope from the public-API tokens under Project Settings > API Access. So invalidating the token from account settings is correct here. The canonical authentication.mdx also documents token creation under Account Settings.

The other three comments were addressed in 508884f (moved the endpoint out of the public-API table into a Note, added a response.ok check to the Node.js example, and scoped the "safe to retry" guidance to in-flight runs).

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
forest	🟢 Ready	View Preview	Jul 7, 2026, 9:04 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[macroscopeapp]

🟡 Medium endpoints/trigger-workflow-webhook.mdx:20

The documentation contradicts itself on how authentication works. The "Authentication" section says any Forest application token whose user can reach the rendering will work (lines 26–32), but the "Revoking access" section says expiring "the" application token makes webhook calls return 401 (line 149). Both cannot be true: if any valid user token works, expiring one token would not revoke access because the caller could switch to another valid token. This leads integrators to set up the wrong credentials and provides false revocation guidance. The page should state that callers must use a specific token associated with the webhook, or clarify what "the application token" refers to.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @reference/api/endpoints/trigger-workflow-webhook.mdx around line 20:

The documentation contradicts itself on how authentication works. The "Authentication" section says any Forest application token whose user can reach the rendering will work (lines 26–32), but the "Revoking access" section says expiring "the" application token makes webhook calls return `401` (line 149). Both cannot be true: if any valid user token works, expiring one token would not revoke access because the caller could switch to another valid token. This leads integrators to set up the wrong credentials and provides false revocation guidance. The page should state that callers must use a specific token associated with the webhook, or clarify what "the application token" refers to.