# Rotate webhook signing secret

`POST /api/webhooks/{id}`

Rotates the endpoint signing secret. The new secret is returned once. Accepted messages continue to use their pinned signing-key version.

Send API requests to your Wildmail application origin. The documentation host does not serve API requests.

## Authentication

- apiKey: Send `Authorization: Bearer <token>` in the request headers. Wildmail scoped kmx_ API token.

- session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies.

Each bullet above is an alternative authentication method.

Required API key scope: `webhooks:admin`.

Audience: management.

## Parameters

### id

path parameter; required.

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string"
  }
}
```

## Responses

### 200

Success

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "endpoint": {
      "$ref": "#/components/schemas/Endpoint"
    },
    "signingSecret": {
      "type": "string"
    }
  },
  "required": [
    "endpoint",
    "signingSecret"
  ]
}
```

### 401

Missing, invalid or revoked credentials.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 403

Required scope or account access missing.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 404

Endpoint not found.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 429



### 503

Secret encryption unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store.

Headers:

```json
{
  "Cache-Control": {
    "description": "Request limiter responses use no-store.",
    "schema": {
      "type": "string"
    }
  }
}
```

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

## Referenced schemas

References resolve against the [OpenAPI specification](/openapi.json).

### #/components/schemas/Endpoint

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused",
        "failing"
      ]
    },
    "signingSecretHint": {
      "type": "string"
    },
    "secretReady": {
      "type": "boolean"
    },
    "subscribedEvents": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "lastDeliveryAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "payloadMapping": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/PayloadMapping"
        },
        {
          "type": "null"
        }
      ],
      "description": "Null uses the standard body. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body."
    }
  },
  "required": [
    "id",
    "name",
    "url",
    "description",
    "status",
    "signingSecretHint",
    "secretReady",
    "subscribedEvents",
    "lastDeliveryAt",
    "payloadMapping"
  ]
}
```

### #/components/schemas/Error

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "limit": {
      "type": "integer"
    }
  },
  "required": [
    "error"
  ]
}
```

### #/components/schemas/PayloadMapping

```json
{
  "type": "object",
  "additionalProperties": false,
  "description": "Version 1 copies and reshapes fields from the standard wildmail.v1 event. Root output must be an object. Missing fields become null and missing arrays become []. Unmapped fields are omitted. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body. Maximum input size 64 KiB, 500 nodes, depth 12 including root, and 128 MiB output. No scripts, constants, fetching, or type conversion. Unsafe keys and pointer segments __proto__, prototype, constructor are rejected.",
  "properties": {
    "version": {
      "const": 1
    },
    "output": {
      "$ref": "#/components/schemas/PayloadObjectNode"
    }
  },
  "required": [
    "version",
    "output"
  ],
  "example": {
    "version": 1,
    "output": {
      "type": "object",
      "fields": {
        "title": {
          "type": "field",
          "path": "/subject"
        },
        "files": {
          "type": "array",
          "path": "/attachments",
          "items": {
            "type": "field",
            "path": "/filename"
          }
        }
      }
    }
  }
}
```

### #/components/schemas/PayloadObjectNode

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "const": "object"
    },
    "fields": {
      "type": "object",
      "propertyNames": {
        "minLength": 1,
        "maxLength": 128,
        "not": {
          "enum": [
            "__proto__",
            "prototype",
            "constructor"
          ]
        }
      },
      "additionalProperties": {
        "$ref": "#/components/schemas/PayloadMappingNode"
      }
    }
  },
  "required": [
    "type",
    "fields"
  ]
}
```

### #/components/schemas/PayloadMappingNode

```json
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/PayloadFieldNode"
    },
    {
      "$ref": "#/components/schemas/PayloadObjectNode"
    },
    {
      "$ref": "#/components/schemas/PayloadArrayNode"
    }
  ]
}
```

### #/components/schemas/PayloadFieldNode

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "const": "field"
    },
    "path": {
      "type": "string",
      "maxLength": 1024,
      "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported."
    }
  },
  "required": [
    "type",
    "path"
  ]
}
```

### #/components/schemas/PayloadArrayNode

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "const": "array"
    },
    "path": {
      "type": "string",
      "maxLength": 1024,
      "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported."
    },
    "items": {
      "$ref": "#/components/schemas/PayloadMappingNode"
    }
  },
  "required": [
    "type",
    "path",
    "items"
  ]
}
```
