Webhook secrets updates

site/about/glossary/integrations/_http-request.qmd

@@ -3,5 +3,5 @@ Refer to the LICENSE file in the root of this repository for details.
 SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial -->
 
 HTTP request
-: A workflow step that sends data from {{< var vm.product >}} to another service.
+: A workflow step that sends data from {{< var vm.product >}} to another service. Header values can reference webhook secrets using `{{secret:name}}` syntax to avoid storing credentials in plaintext.
 

site/about/glossary/integrations/_secret.qmd

@@ -3,5 +3,5 @@ Refer to the LICENSE file in the root of this repository for details.
 SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial -->
 
 secret
-: A credential that stores the API key, password, or token required by an external service for authentication.
+: A credential that stores the API key, password, or token required by an external service for authentication. There are two types: _integration secrets_ for authenticating persistent connections to external platforms, and _webhook secrets_ for authenticating outgoing HTTP Request steps in workflows via `{{secret:name}}` syntax.
 

site/guide/integrations/integrations-examples.qmd

@@ -23,19 +23,19 @@ Adapt these usage examples for your own workflows or connections to interact wit
 - [x] {{< var link.login >}}
 - [x] You are a [{{< fa hand >}} Customer Admin]{.bubble} or assigned another role with sufficient permissions to configure workflows.[^1]
 - [x] You understand how to configure workflows and add steps to workflows.[^2]
-- [x] Secrets are configured for any external systems that require authentication.[^3]
+- [x] Secrets are configured for any external systems that require authentication: integration secrets for connections, webhook secrets for HTTP Request step headers.[^3]
 - [x] Connections are configured for any external systems you plan to integrate with.[^4]
 - [x] You have admin access to the external systems you plan to integrate with.
 
 :::
 
 ## Workflow examples
 
-These examples use HTTP request or webhooks to integrate with external systems:
+These examples use HTTP requests or webhooks to integrate with external systems:
 
-- An *HTTP request* step sends data from {{< var vm.product >}} to another service. A workflow can notify a partner tool when a model reaches a certain state or request an update in an external system. This pattern is useful when {{< var vm.product >}} owns the event and needs to push it outward.
+- An _HTTP request_ step sends data from {{< var vm.product >}} to another service. A workflow can notify a partner tool when a model reaches a certain state or request an update in an external system. This pattern is useful when {{< var vm.product >}} owns the event and needs to push it outward.
 
-- A *webhook* step does the opposite. Another system sends a POST request to  start a {{< var vm.product >}} workflow or to continue a workflow that is paused while waiting for a webhook to continue. This lets external tools trigger actions inside {{< var vm.product >}} when an event occurs on their side.
+- A _webhook_ step does the opposite. Another system sends a POST request to  start a {{< var vm.product >}} workflow or to continue a workflow that is paused while waiting for a webhook to continue. This lets external tools trigger actions inside {{< var vm.product >}} when an event occurs on their side.
 
 ### Create a Jira ticket
 
@@ -64,6 +64,11 @@ To create a Jira ticket when model validation requires attention:
    - **[headers]{.smallcaps}** — Add:
      - `Content-Type`: `application/json`
      - `Authorization`: `Bearer {{Jira Personal Access Token}}`
+
+   ::: {.callout-tip title="Use webhook secrets for credentials"}
+   Instead of entering credentials in plaintext, use a webhook secret: `Bearer {{secret:jira_pat}}`. See [Manage secrets](manage-secrets.qmd#webhook-secrets).
+   :::
+
    - **[body type]{.smallcaps}** — JSON
    - **[body]{.smallcaps}** — Use the following JSON payload:
 
@@ -110,6 +115,11 @@ To create a ServiceNow incident when a data drift issue is detected during ongoi
     - **[headers]{.smallcaps}** — Add:
       - `Content-Type`: `application/json`
       - `Authorization`: `Basic {{ServiceNow Credentials}}`
+
+   ::: {.callout-tip title="Use webhook secrets for credentials"}
+   Instead of entering credentials in plaintext, use a webhook secret: `Basic {{secret:servicenow_creds}}`. See [Manage secrets](manage-secrets.qmd#webhook-secrets).
+   :::
+
     - **[body type]{.smallcaps}** — JSON
     - **[body]{.smallcaps}** — Use the following JSON payload:
 

site/guide/integrations/manage-secrets.qmd

@@ -6,7 +6,7 @@ title: "Manage secrets"
 date: last-modified
 ---
 
-Secrets centralize the credentials for your integrations so you can reference them in connection configurations. 
+Secrets centralize the credentials for your integrations so you can reference them in connection configurations and HTTP Request workflow steps.
 
 You store each secret once and then reuse it across supported integrations.
 
@@ -20,19 +20,23 @@ You store each secret once and then reuse it across supported integrations.
 
 :::
 
-## Add secrets
+## Integration secrets
+
+Integration secrets authenticate persistent connections to external platforms. You store each secret once and then reuse it across supported integrations by selecting it from a dropdown when configuring a connection.
+
+### Add integration secrets
 
 1. In the left sidebar, click **{{< fa gear >}} Settings**.
 
-2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**.
+2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**, then open the **Integration Secrets** tab.
 
 3. Click **{{< fa plus >}} Add Secret**.
 
 4. Fill in the details:
 
    - **[secret name]{.smallcaps}** — Enter an easily identifiable label that indicates which system the secret belongs to.
    - **[description]{.smallcaps}** (optional) — Summarize when to use the secret or who owns it so other admins know whether it is safe to re-use.
-   - **[secret value]{.smallcaps}** — Paste the credential exactly as issued by the external system. The value is encrypted and never displays it in plaintext again.
+   - **[secret value]{.smallcaps}** — Paste the credential exactly as issued by the external system. The value is encrypted and never displayed in plaintext again.
    - **[expiration date]{.smallcaps}** (optional) — Set a rotation reminder if the external system enforces key expiry.
 
 5. Click **Create Secret**. 
@@ -45,19 +49,19 @@ Recommended: Create a new secret and update integrations that should use it.<br>
 :::
 :::
 
-## View details
+### View integration secret details
 
 1. In the left sidebar, click **{{< fa gear >}} Settings**.
 
-2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**.
+2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**, then open the **Integration Secrets** tab.
 
 3. Click the secret you want to view.
 
-## Edit secrets
+### Edit integration secrets
 
 1. In the left sidebar, click **{{< fa gear >}} Settings**.
 
-2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**.
+2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**, then open the **Integration Secrets** tab.
 
 3. Click the secret you want to change.
 
@@ -70,11 +74,11 @@ Recommended: Create a new secret and update integrations that should use it.<br>
 
 6. Click **Update Secret** to save your changes. 
 
-## Revoke secrets
+### Revoke integration secrets
 
 1. In the left sidebar, click **{{< fa gear >}} Settings**.
 
-2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**.
+2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**, then open the **Integration Secrets** tab.
 
 3. Hover over the secret you want to change.
 
@@ -84,15 +88,99 @@ Recommended: Create a new secret and update integrations that should use it.<br>
 
 Revocation immediately disables the secret so it can no longer be used, but does not remove it.
 
-## Delete secrets
+### Delete integration secrets
 
 ::: {.callout-warning title="Deleting a secret is permanent."}
 Be sure to update any connections that depend on this secret before deleting it.
 :::
 
 1. In the left sidebar, click **{{< fa gear >}} Settings**.
 
-2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**.
+2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**, then open the **Integration Secrets** tab.
+
+3. Hover over the secret you want to remove.
+
+4. When **{{< fa ellipsis-vertical >}}** appears, click it, then select **{{< fa trash >}} Delete**.
+
+5. In the confirmation dialog, select **OK** to confirm deletion.
+
+## Webhook secrets
+
+Webhook secrets authenticate outgoing HTTP requests in workflows. Instead of hardcoding credentials directly into HTTP Request step header values, you store secrets once and reference them using `{{secret:name}}` syntax. HTTPS is enforced when secrets are used.
+
+### Add webhook secrets
+
+1. In the left sidebar, click **{{< fa gear >}} Settings**.
+
+2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**, then open the **Webhook Secrets** tab.
+
+3. Click **{{< fa plus >}} Add Secret**.
+
+4. Fill in the details:
+
+   - **[secret name]{.smallcaps}** — Enter an easily identifiable label. Use this name to reference the secret: `{{secret:secret_name}}`.
+   - **[description]{.smallcaps}** (optional) — Summarize what the secret is used for.
+   - **[secret value]{.smallcaps}** — Paste the credential. The value is encrypted at rest and never displayed in plaintext again.
+   - **[expiration date]{.smallcaps}** (optional) — Set a rotation reminder if the credential expires.
+
+5. Click **Create Secret**.
+
+The secret can now be referenced in HTTP Request step headers using `{{secret:secret_name}}` syntax.
+
+#### Usage example
+In a workflow HTTP Request step, add a header:
+
+- **Header Name**: `Authorization`  
+- **Header Value**: `Bearer {{secret:jira_pat}}`
+
+At runtime, the workflow engine replaces `{{secret:jira_pat}}` with the stored value and sends the request over HTTPS.
+
+### View webhook secret details
+
+1. In the left sidebar, click **{{< fa gear >}} Settings**.
+
+2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**, then open the **Webhook Secrets** tab.
+
+3. Click the secret you want to view.
+
+### Edit webhook secrets
+
+1. In the left sidebar, click **{{< fa gear >}} Settings**.
+
+2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**, then open the **Webhook Secrets** tab.
+
+3. Click the secret you want to change.
+
+4. Make your changes. For example:
+
+   - **[secret value]{.smallcaps}** — Paste a new value if the credential was rotated.
+   - **[expiration date]{.smallcaps}** (optional) — Extend the expiry window.
+
+5. Click **Update Secret** to save your changes.
+
+### Revoke webhook secrets
+
+1. In the left sidebar, click **{{< fa gear >}} Settings**.
+
+2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**, then open the **Webhook Secrets** tab.
+
+3. Hover over the secret you want to revoke.
+
+4. When **{{< fa ellipsis-vertical >}}** appears, click on it and select **{{< fa triangle-exclamation >}} Revoke**.
+
+5. On the confirmation dialogue that appears, select **OK** to confirm revocation.
+
+Revocation immediately disables the secret. Any HTTP Request workflow steps referencing it will fail until you update them to use an active secret.
+
+### Delete webhook secrets
+
+::: {.callout-warning title="Deleting a secret is permanent."}
+Be sure to update any HTTP Request workflow steps that depend on this secret before deleting it.
+:::
+
+1. In the left sidebar, click **{{< fa gear >}} Settings**.
+
+2. Under {{< fa puzzle-piece >}} Integrations, select **Secrets**, then open the **Webhook Secrets** tab.
 
 3. Hover over the secret you want to remove.
 

site/guide/workflows/_conditional-requirements.qmd

@@ -149,6 +149,8 @@ Enter in optional headers to include with your request:
 
 2. Provide a **Header Name** and **Header Value**.
 
+To avoid storing credentials in plaintext, use `{{secret:name}}` syntax to reference a webhook secret.^[[Manage secrets](/guide/integrations/manage-secrets.qmd#webhook-secrets)]
+
 :::
 
 

site/guide/workflows/_workflow-step-types.qmd

@@ -213,6 +213,8 @@ Sends a HTTP request with optional additional conditions.^[[Conditional requirem
 
     1. Click **{{< fa plus >}} Add Header** to enter a header.
     2. Provide a **Header Name** and **Header Value**.
+
+    To avoid storing credentials in plaintext, use webhook secrets: enter `{{secret:name}}` as the header value. At runtime, the workflow engine replaces the placeholder with the stored secret value. See [Manage secrets](/guide/integrations/manage-secrets.qmd#webhook-secrets).