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

# Rotate Webhook Secret

> Generate a new HMAC signing secret for a webhook endpoint.

Replaces the HMAC signing secret (`whsec_...`) for one webhook endpoint. The new secret is returned **exactly once** in the response — it is never exposed by list endpoints, so store it immediately.

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token formatted as `Bearer gork_live_...`. Requires the `webhooks:write` scope.
</ParamField>

### Path parameters

<ParamField body="id" type="string" required>
  The webhook ID (`whk_...`).
</ParamField>

<Warning>
  Rotation takes effect immediately: deliveries signed with the old secret will fail your `X-Gork-Signature` verification. Update your verifier before or at the same time as rotating.
</Warning>

### Response

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      The webhook ID.
    </ResponseField>

    <ResponseField name="url" type="string">
      The endpoint URL.
    </ResponseField>

    <ResponseField name="subscribedEvents" type="string[]">
      Event types delivered to this endpoint.
    </ResponseField>

    <ResponseField name="isActive" type="boolean">
      Whether the endpoint is active.
    </ResponseField>

    <ResponseField name="secret" type="string">
      The new `whsec_...` signing secret. Shown only this one time.
    </ResponseField>

    <ResponseField name="warning" type="string">
      Reminder to update your signature verifiers immediately.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.gork.email/v1/webhooks/whk_1a2b3c4d5e6f/rotate-secret \
    -H "Authorization: Bearer gork_live_YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  import { Gork } from "@gork/sdk"

  const gork = new Gork({ apiKey: process.env.GORK_API_KEY })

  const rotated = await gork.webhooks.rotateSecret("whk_1a2b3c4d5e6f")
  // Save rotated.secret somewhere safe — it will never be shown again.
  ```

  ```python Python theme={null}
  import requests, os

  res = requests.post(
      "https://api.gork.email/v1/webhooks/whk_1a2b3c4d5e6f/rotate-secret",
      headers={"Authorization": f"Bearer {os.getenv('GORK_API_KEY')}"},
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": {
      "id": "whk_1a2b3c4d5e6f",
      "url": "https://agent.acmecorp.com/hooks/gork",
      "subscribedEvents": ["email.received", "email.sent"],
      "isActive": true,
      "secret": "whsec_9f2c4a1e8b7d6f5a3c2e1d0b9a8f7e6d",
      "warning": "This webhook secret is displayed once. Update your HMAC signature verifiers immediately."
    }
  }
  ```
</ResponseExample>

| Code                | HTTP | Meaning                                              |
| ------------------- | ---- | ---------------------------------------------------- |
| `webhook_not_found` | 404  | No webhook with this ID exists in your organization. |