---
title: "Coordinate webhook secret rotation"
locale: en
url: https://tlg.builera.app/en/docs/agent-playbooks/rotate-webhook-secret
verified: 2026-10-24
app_version: "2.0"
---

# Coordinate webhook secret rotation

The agent prepares and checks the secret change, while a person performs the rotation on the web.


## Goal

You coordinate a signing secret change without losing events or putting secrets in the conversation. The agent prepares and checks; an authorized person performs the rotation on the web.

## Permissions needed

- `webhooks.read` to read webhooks and delivery history within the granted scope.
- `webhooks.manage` to send tests.
- Permission to operate the external receiver service, if you are assigned to check it.

`integrations.manage` expands webhook scope but does not remove human-only restrictions.

The secret rotation operation is marked `humanOnly: true`. It is not in `PUBLIC_OPS`, so there is no public MCP tool or public REST operation page for the agent to use.

## Ask the person before

Ask which webhook needs rotation, who will update the receiver, the transition period and where the new secret will be stored.

If you suspect the secret has leaked, ask the person to decide whether to pause the webhook while addressing it. Do not extend acceptance of the old key yourself just to avoid errors.

## Check first

Call `whoami`. Read [`webhooks.get`](https://tlg.builera.app/en/docs/reference/rest/webhooks.get) and [`webhooks.deliveries_list`](https://tlg.builera.app/en/docs/reference/rest/webhooks.deliveries_list) through `tools_run`.

Confirm the destination URL and webhook owner. Check whether the receiver can accept the old and new secrets at the same time. Do not ask the person to paste a secret into a message for you to check.

## Steps

1. Record delivery health before the change.
2. Agree on how to update the receiver's secret store.
3. Prepare a receiver deployment that can verify multiple valid keys.

> [!IMPORTANT]
> Stop point — ask the person
>
> The agent must not call the secret rotation operation, use `tools_run` to get around `humanOnly`, or switch to an internal server function. Ask an authorized person to perform it on the web.

4. Ask the person to open **Settings → Webhook** and select the webhook.
5. Ask the person to open **Settings & secrets**.
6. Ask the person to choose **Rotate secret**.
7. Ask the person to save the new secret directly in the receiver's secret store.
8. After the receiver has been updated, call [`webhooks.test`](https://tlg.builera.app/en/docs/reference/rest/webhooks.test), using `webhooks_test` if available or `tools_run`.
9. Read the test delivery and check the receiver's verification result.

The default transition period is **24 hours**. The system allows at most **2 active keys** to sign at once. The receiver accepts a signature matching one valid key.

![Webhook settings tab with the secret area fully hidden](https://tlg.builera.app/docs-media/en/webhook-secret-settings.webp "Secret hidden")

## Check after

Check that new events are received successfully, not just events signed with the old key. Monitor deliveries after the change and check deduplication.

When the old key expires, confirm that the receiver still works with the new key. The report should contain only the webhook ID, results and times, not secret values.

## On errors

If signatures do not match, check the secret source, raw body and machine clock. Do not disable signature verification as a temporary recovery measure.

If the new secret has been lost, refer the person to the web interface. The agent has no public API path to read the secret again.

## When to stop

Stop when a human-only action is needed, you lack permission to update the receiver, or you have not proved that the receiver accepts the new key.

See [signature verification](https://tlg.builera.app/en/docs/integrations/webhook-receivers) and [keeping secrets](https://tlg.builera.app/en/docs/safety/keep-secrets).