# /webhook/rotate-secret

Rotates the webhook signing secret for a specific webhook.
## Purpose
Allows a partner to rotate their webhook_secret for security purposes. The old secret remains valid for a 24-hour grace period so the partner can update their verification logic without missing notifications.
## When to use
Use this endpoint to:
- Rotate the signing secret if it may have been compromised
- Periodically rotate secrets as a security best practice
- Re-issue a secret if the partner lost the original

## What happens next
1. A new webhook_secret is generated (256-bit, 64-char hex)
2. The current secret is moved to a grace period (24 hours)
3. Both old and new secrets are valid during the grace period
4. After 24 hours, only the new secret is valid for outbound signatures

## Authentication
Requires `x-client-id` and `x-secret-key` headers.
## Notes
- The old secret remains valid for signature verification for 24 hours after rotation
- If rotated again during an active grace period (double rotation), the oldest secret is immediately invalidated
- The new secret is used for signing outbound payloads immediately
- Returns 404 if no webhook registration exists for the partner

## Common errors
- `401` Invalid credentials
- `404` No webhook configuration exists for this partner
- `500` Internal error during rotation

Endpoint: POST /webhook/rotate-secret
Version: 1.0.0

## Header parameters:

  - `x-client-id` (string, required)
    Unique identifier assigned to the integrating client.

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

  - `x-secret-key` (string, required)
    Secret authentication key associated with the client.

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

## Request fields (application/json):

  - `webhook_id` (string, required)
    UUID v4 identifier of the webhook to rotate the secret for.
Error codes: required=400001, type=400002

## Response 200 fields (application/json):

  - `status` (string)
    Response status (success)

  - `data` (object)
    Rotation result

  - `data.webhook_secret` (string)
    The new 64-character hex HMAC signing secret. Store this securely.

  - `data.grace_period_expires_at` (string)
    ISO 8601 UTC timestamp when the old secret will no longer be accepted for verification.

  - `data.message` (string)
    Human-readable confirmation message.

## Response 401 fields (application/json):

  - `errors` (array)
    List of authentication errorsError catalog for 401 (click to expand)CodeDescription401000Invalid credentials

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

## Response 404 fields (application/json):

  - `errors` (array)
    List of not found errorsError catalog for 404 (click to expand)CodeDescription404000No webhook configuration exists for this partner

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

## Response 500 fields (application/json):

  - `errors` (array)
    List of server errorsError catalog for 500 (click to expand)CodeDescription500000Internal server error during secret rotation

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)