---
updatedAt: 2026-07-30T11:04:44.000Z
agentTools:
  projectIndex: https://developer.orangelogic.com/llms.txt
---

# Generate a secret key for a webhook signature

Generate or update the secret key for a webhook signature

This call returns the newly-generated secret key. When the subscription for which you’ve generated the key is triggered, the signature appears in the `X-ol-signature` header, encrypted in **Base64** and prepended with `v1,`.

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/354db3364f94028ee9e76ce539ebed9cdf45edd736eca9085fcaaf59f68d1421-header_signature.png",
        null,
        "The signature displayed in the webhook’s header information."
      ],
      "align": "center",
      "sizing": "650px",
      "border": true,
      "caption": "The signature displayed in the webhook’s header information"
    }
  ]
}
[/block]

### Update a subscription’s secret keys

If your organization experiences a security event, you might need to update your secret keys. To do this, run this API call.

#### Zero downtime secret rotation

When you update a subscription, it takes time for a webhook recipient to process secret key changes. If a webhook is sent **before** the key change is processed, the recipient could reject a valid webhook because it expects an obsolete key.

As a solution, Orange Logic webhook signatures allow for **zero downtime secret rotation**, where the webhook sends both the old signature and the new signature while the recipient processes the key change. Both signatures appear in the `x-ol-signature` header. The old signature is prepended with `v1,` and the new signature is prepended with `v1a,`.

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/d7735eba59247abd99a4030db2ab12c66f1d3cd247ab2e14ed1d38a76a17aa8b-zero-downtime_rotation_api_secrets.png",
        null,
        "The old and updated signatures in the webhook headers."
      ],
      "align": "center",
      "sizing": "750px",
      "border": true,
      "caption": "The old and updated signatures in the webhook header"
    }
  ]
}
[/block]

By default, Orange Logic sends both signatures for one hour after the key is changed, but you can customize the secret key rotation time period in the [Configure Modules Advanced Configuration](https://developer.orangelogic.com/reference/use-webhook-signatures#activate-and-configure-webhook-signatures).

For more technical information about zero downtime secret rotation, refer to Github’s <a href= "https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#webhook-headers-sending-metadata-to-consumers>" target="_blank">documentation on standard webhooks</a>.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "webhooks",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://{orangelogicURL}/webapi/extensibility/webhook/subscription/",
      "variables": {
        "orangelogicURL": {
          "default": "orangelogicURL"
        }
      }
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://example.com/oauth2/token",
            "scopes": {}
          }
        }
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/rotatesecret_22P_v1": {
      "post": {
        "summary": "Generate a secret key for a webhook signature",
        "description": "Generate or update the secret key for a webhook signature",
        "operationId": "add-or-update-a-webhook-signature",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "newSecret": {
                    "type": "string",
                    "description": "An alphanumeric string to be the <code>newSecret</code>. If you leave this parameter empty, Orange Logic generates a random secret and adds it to the response body.",
                    "default": "\"\""
                  },
                  "subscriptionID": {
                    "type": "string",
                    "description": "The subscriptionID of the webhook you are creating a secret for."
                  }
                }
              },
              "examples": {
                "Request Example": {
                  "value": {
                    "newSecret": "",
                    "subscriptionId": "Mango1"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n \"newSecret\": \"GNSlz1PkDXih\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "newSecret": {
                      "type": "string",
                      "example": "GNSlz1PkDXih"
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false,
        "security": []
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```