> ## Documentation Index
> Fetch the complete documentation index at: https://docs.occtoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Signing secrets

> Store the secret a webhook subscription is created with, verify deliveries against it, and rotate it when it leaks.

Every **Webhook** subscription is created with a signing secret. Occtoo signs each delivery with it and sends the signature in a `webhook-signature` header, so your endpoint can prove the request came from Occtoo. Queue subscriptions have no secret — access to the queue is the credential.

## Store it at creation

Creating a webhook subscription opens **Store your signing secret**. Copy it there and then: the API returns the secret only at creation and at rotation, and Studio has no way to show it again.

The dialog will not close on the first attempt if you have not copied the value — it warns first, and the button becomes **Continue without copying** so a second click still lets you through.

<Warning>
  Leaving without the secret means you cannot validate deliveries. Rotate the secret to get a new value for subsequent deliveries, then store it before closing the dialog.
</Warning>

## Verify a delivery

Validate the `webhook-signature` header on every event delivery request with the stored secret, and reject anything that does not match. Deliveries are at least once, so the same event can arrive twice — deduplicate on the `webhook-id` header to process it exactly once.

## Rotate the secret

Rotate when the secret leaks, or on whatever schedule your own policy sets.

<Steps>
  <Step title="Open the dialog">
    On the subscription page, open the kebab menu and choose **Rotate signing secret**. The item only exists for webhook subscriptions.

    <img src="https://mintcdn.com/occtoo/QBYMHKVxFRfbTQTY/images/guides/studio/events/rotate-signing-secret.png?fit=max&auto=format&n=QBYMHKVxFRfbTQTY&q=85&s=5ec5b7b8913d855f3af191bed45954d3" alt="The rotate signing secret confirmation" width="512" height="164" data-path="images/guides/studio/events/rotate-signing-secret.png" />
  </Step>

  <Step title="Rotate">
    Click **Rotate secret**. The new secret appears once, under the same copy guard as at creation — the close button reads **Close anyway** until you have copied it.
  </Step>

  <Step title="Update every receiver">
    <Warning>
      Occtoo uses the new secret for subsequent deliveries, including retries of pending events. Update every receiver to accept it so those deliveries pass signature checks. A request already in progress may still be signed with the old secret. Rotation does not invalidate signatures already made with the old secret; your receiver controls which secrets it accepts.
    </Warning>
  </Step>
</Steps>
