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

# Rotate a webhook secret

> Replace the signing secret without missing a verification.

export const Notice = ({kind = "note", title, children}) => {
  const kinds = {
    warning: {
      label: "User notice",
      icon: <>
          <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" />
          <path d="M12 9v4" />
          <path d="M12 17h.01" />
        </>
    },
    gotcha: {
      label: "Gotcha",
      icon: <>
          <circle cx="12" cy="12" r="10" />
          <path d="M12 16v-4" />
          <path d="M12 8h.01" />
        </>
    },
    note: {
      label: "Note",
      icon: <>
          <circle cx="12" cy="12" r="10" />
          <path d="M12 16v-4" />
          <path d="M12 8h.01" />
        </>
    }
  };
  const k = kinds[kind];
  return <div className="notice my-6 rounded-xl border border-zinc-200 bg-white p-5 dark:border-zinc-800 dark:bg-zinc-950">
      <div className={`${kind === "warning" ? "not-prose flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-red-400/80 dark:text-red-400/70" : kind === "gotcha" ? "not-prose flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-amber-500/80 dark:text-amber-400/70" : "not-prose flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-zinc-400 dark:text-zinc-500"}`}>
        <svg className="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
          {k.icon}
        </svg>
        {k.label}
      </div>
      {title && <div className="not-prose mt-2 text-base font-semibold text-zinc-900 dark:text-zinc-100">{title}</div>}
      <div className="notice-body mt-3 text-sm leading-6 text-zinc-700 dark:text-zinc-300">{children}</div>
    </div>;
};

Replaces the webhook's signing secret. The response includes the new `secret`; like [Create](/agents-api/webhooks/create), this is the only time it is returned, so store it securely. Deliveries are signed at send time, so events (including retries already in flight) are signed with the new secret from this point on.

**Returns** the webhook object plus its new `secret`.

<Notice kind="warning" title="Accept both secrets during the switch">
  Update your receiver to accept the old and the new secret before calling this endpoint. The SDK verify helpers take a list for exactly this overlap: `verify_webhook(body, sig, ts, ["whsec_old", "whsec_new"])`. Remove the old secret once deliveries verify against the new one.
</Notice>

***

## Path parameters

<ParamField path="webhook_id" type="string" required>
  The webhook's `id` (UUID).
</ParamField>

***

## Examples

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://agp.eu.hcompany.ai/api/v2/webhooks/f47ac10b-58cc-4372-a567-0e02b2c3d479/rotate \
    -H "Authorization: Bearer $HAI_API_KEY"
  ```

  ```python Python theme={"system"}
  from hai_agents import Client

  client = Client()

  webhook = client.webhooks.rotate_webhook_secret(webhook_id="f47ac10b-58cc-4372-a567-0e02b2c3d479")
  print(webhook.secret)  # store it now; it is never returned again
  ```

  ```typescript TypeScript theme={"system"}
  import { HaiAgentsClient } from "hai-agents";

  const client = new HaiAgentsClient();

  const webhook = await client.webhooks.rotateWebhookSecret({ webhookId: "f47ac10b-58cc-4372-a567-0e02b2c3d479" });
  console.log(webhook.secret); // store it now; it is never returned again
  ```
</CodeGroup>

```json Response theme={"system"}
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "url": "https://example.com/hooks/h",
  "enabled_events": ["*"],
  "description": "Production listener",
  "disabled": false,
  "last_delivery_status": "succeeded",
  "last_delivery_error": null,
  "last_delivery_at": "2026-07-02T08:30:00Z",
  "last_success_at": "2026-07-02T08:30:00Z",
  "consecutive_failures": 0,
  "created_at": "2026-06-11T15:04:05Z",
  "updated_at": "2026-07-02T09:00:00Z",
  "secret": "whsec_nZbY0eXaMpLeOnLyDoNotUse0aQ3rT5uV7wX9yZ1aB3c"
}
```

***

## Errors

| Status | Cause                                       |
| ------ | ------------------------------------------- |
| `404`  | Webhook not found or you don't have access. |