---
title: "Rotate a webhook signing secret"
method: POST
path: "/webhooks/{id}/rotate-secret"
tags: ["Webhooks"]
---

# Rotate a webhook signing secret

`POST /webhooks/{id}/rotate-secret`

## Request

- Base URL: `https://api.rizamo.com/v1`
- URL: `https://api.rizamo.com/v1/webhooks/{id}/rotate-secret`
- Auth: HTTP bearer

A new signing secret, in the answer and only there. For 24 hours each delivery carries two signatures in `webhook-signature`, one with each secret, so the receiver can switch without losing any; then only the new one.

## Path parameters

- `id` string, required: The webhook endpoint's id (`wh_`).

## Headers

- `Idempotency-Key` string

## Response `200`

OK

- WebhookSecret
  - `endpoint` WebhookEndpoint, required
    - `id` string, required
    - `url` string, uri, required
    - `description` string, required
    - `events` WebhookEventType[], nullable, required: The event types it receives. Null: every type, those Rizamo adds later included. The inbox's (`comment.received`, `message.received`, `message.sent`) and comment automations' (`comment_automation.*`) carry what people wrote: an endpoint a key or agent made, or last pointed at its `url`, gets them only if it had `inbox:read` (`automations:read` for automations), whatever this lists.
    - `profileIds` string[], nullable, required: Only events of these profiles, and of those only the ones its person reaches now (`onBehalfOf`). Null: every profile's, and the events of no profile. Empty once every profile it was limited to is deleted: it is then disabled. Someone limited to some profiles only sees and makes endpoints within them.
    - `status` 'active' | 'failing' | 'disabled', required: active: sends, and its last attempt was delivered (or none was made yet). failing: sends, but its last attempt failed; after 10 failures in a row its deliveries wait while one at a time tries it (`breaker`). disabled: sends nothing, see `disabledReason`.
    - `disabledReason` 'by_request' | 'gone' | 'failing' | 'profile_deleted', nullable, required: by_request: someone set `enabled` to false. gone: the endpoint answered 410 Gone. failing: its breaker was open and nothing got through for 5 days; for these two Rizamo emails the team's owners and editors. profile_deleted: every profile it was limited to was deleted, which leaves `profileIds` empty; give it profiles to enable it again. Null while it sends.
    - `breaker` 'closed' | 'open', required: open: it failed 10 times in a row, so its deliveries wait and one at a time tries it every 15 minutes; the first one delivered, or a test that gets through, sends the rest. closed: deliveries go as they come. A new `url` starts closed.
    - `failingSince` string, date-time, nullable, required: Its first failed attempt of the failures in a row (failures hours apart, further than the retries' spacing, start anew). Null once an attempt is delivered.
    - `disablesAt` string, date-time, nullable, required: When Rizamo disables it unless an attempt is delivered first: `failingSince` and 5 days, while its breaker is open. Null otherwise.
    - `successRate` number, nullable, required: Of the attempts in the last 7 days, the percent delivered (a 2xx answer). Null with none.
    - `lastDeliveryAt` string, date-time, nullable, required: When Rizamo last tried to deliver to it, whatever the answer.
    - `createdBy` union, required
      - object
        - `type` 'agent', required
        - `agent` 'claude' | 'chatgpt' | 'claudecode' | 'cursor' | 'codex' | 'gemini' | 'perplexity' | 'openclaw' | 'n8n' | 'make' | 'zapier', nullable, required
        - `name` string, required
        - `agentId` string
        - `onBehalfOf` object: The person whose agent it is, who connected it and whom it acts as, with their role: "Ana via Claude Code". Events from before 2026-11-02 have it too, with the person's name now. Left out of an agent with no person, and of other records from before. After the person's erasure, `name` is "A former member" and `userId` empty.
          - `userId` string, required
          - `name` string, required
      - object
        - `type` 'user', required
        - `userId` string, required
        - `name` string, required
        - `initials` string, required
      - object
        - `type` 'api_key', required
        - `keyId` string, required
        - `name` string, required
      - object
        - `type` 'automation', required
        - `automationId` string, required
        - `name` string, required
    - `onBehalfOf` object, nullable, required: The person it sends for: whoever made it or last pointed it at its `url`, or the person behind the API key or agent that did. It sends only events of the profiles they reach now (events of no profile only while they reach every profile), owners and they alone see and manage it, and it is deleted when they leave the team. Null once they are no longer on the team: it sends nothing until an owner changes it, which makes them its person.
      - `userId` string, required
      - `name` string, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `secret` string, required: The signing secret (`whsec_` and base64), shown only now: keep it where your receiver reads it. Each delivery's `webhook-signature` is `v1,` and the base64 HMAC-SHA256, keyed with the base64 after `whsec_`, of `<webhook-id>.<webhook-timestamp>.<body>`.

## Other responses

- `400`: `invalid_request`: A field is missing or wrong, or the request cannot be done as asked: the message names the field or says what to change.
- `401`: `unauthorized`: No API key or sign-in, or the key does not work: it was deleted, or it expired.
- `403`: `forbidden`: The caller may not do this: the key or agent lacks the scope (the message names it), or the action needs another role or a fresh sign-in.
- `404`: `not_found`: No such object, or it is outside your team or the profiles your key reaches.
- `409`: `conflict`: The object's state does not allow it now, such as an account that needs a new login. `queue_empty`: A post with `queue: true` whose profile has no posting times: set them, or give a `scheduledAt`. `queue_full`: No posting time free for the post's accounts in the next 90 days: add times, or give a `scheduledAt`. `idempotency_key_in_use`: A request with this `Idempotency-Key` is still running: try again in a moment.
- `413`: `payload_too_large`: The body is over 1 MB: files go up through the upload links of `POST /v1/media`.
- `415`: `unsupported_media_type`: The body is not JSON: send it with `Content-Type: application/json`.
- `422`: `capability_missing`: The account cannot do this: see its `capabilities`. `idempotency_key_reused`: This `Idempotency-Key` was used for a different request in the last 24 hours: send a new key.
- `429`: `rate_limited`: Over one of Rizamo's limits, or a network asked Rizamo to slow down: wait for `Retry-After` seconds, or as long as the message says.
- `500`: `internal`: Our side failed: retry, and send the `requestId` if it keeps failing.
- `503`: `timeout`: The request took too long to work out, most often a report: try again in a moment, or ask a report for a shorter period or one profile.

---

[API](https://skmtc.dev/rizamo/apis/rizamo-api.md) - [All operations](https://skmtc.dev/rizamo/apis/rizamo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rizamo/apis/rizamo-api/revisions/31b0c1b1ffb5?raw)
