# rotateWebhookSubscriptionSecret

Mutation

Rotate a webhook subscription signing secret. Returns the new secret once.

Available to agents as MCP tool `rotateWebhookSubscriptionSecret` — see [Write tools](/api/v2/docs/mcp/write-tools#rotate-webhook-subscription-secret).

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `ID!` | Yes | — | UUID of the subscription to rotate. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `secret` | `String` | The new plaintext signing secret (whsec_-prefixed). Returned only here and from createWebhookSubscription, and never shown again, so store it immediately. During the 24h dual-sign overlap, deliveries are signed with both the new and previous secrets (two v1= values in X-Archive-Signature), so a receiver that accepts either signature cuts over without dropping a delivery. The whsec_ prefix is part of the HMAC key; do not strip it. |
| `userErrors` | [`[UserError!]!`](/api/v2/docs/types/user-error) | List of user-facing errors. Populated only when rotation failed. |
| `webhookSubscription` | [`WebhookSubscription`](/api/v2/docs/types/webhook-subscription) | The subscription after rotation. Null when not found. |

## Examples

### Rotate a webhook signing secret

Mint a new signing secret, returned exactly once. The previous secret keeps verifying for a 24h overlap so you can roll the new one out without dropping deliveries.

```graphql
mutation RotateWebhookSubscriptionSecretDefault($id: ID!) {
  rotateWebhookSubscriptionSecret(id: $id) {
    webhookSubscription {
      id
      name
      status
    }
    secret
    userErrors {
      field
      message
    }
  }
}
```

Variables:

```json
{
  "id": "eb418e28-bf9d-5350-b87b-446a6813bca4"
}
```

Response — HTTP 200:

```json
{
  "data": {
    "rotateWebhookSubscriptionSecret": {
      "webhookSubscription": {
        "id": "eb418e28-bf9d-5350-b87b-446a6813bca4",
        "name": "Northwind Order Fulfilment",
        "status": "ACTIVE"
      },
      "secret": "whsec_EXAMPLE_SECRET_SHOWN_ONCE_DO_NOT_USE",
      "userErrors": []
    }
  }
}
```