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

# Regenerate Webhook Secret

> Generate a new webhook signing secret, immediately invalidating the previous one. POST /webhooks/secret/regenerate. Requires webhooks:write scope.

## Overview

Generate a new webhook signing secret. The previous secret is **immediately invalidated** — webhooks will be signed with the new secret from this point forward.

## When to Use

* Your current `webhookSecret` has been compromised or exposed
* Rotating secrets as part of your security policy
* You've lost the secret and need a new one

## Response Fields

| Field           | Type   | Description                                             |
| --------------- | ------ | ------------------------------------------------------- |
| `webhookSecret` | string | New signing secret — store immediately, shown only once |
| `secretNote`    | string | Reminder that the secret is shown only once             |

## Migration Strategy

To avoid dropping webhooks during rotation:

<Steps>
  <Step title="Regenerate Secret">
    Call this endpoint to get a new secret
  </Step>

  <Step title="Update Your Server">
    Deploy the new secret to your webhook handler
  </Step>

  <Step title="Verify">
    Send a test webhook with `POST /webhooks/test` to confirm the new secret validates correctly
  </Step>
</Steps>

<Warning>
  The new `webhookSecret` is shown **only once** in the response. Store it immediately. The old secret stops working as soon as this endpoint is called.
</Warning>


## OpenAPI

````yaml v3.20/openapi.json POST /webhooks/secret/regenerate
openapi: 3.1.0
info:
  title: FYATU API v3
  description: >-
    FYATU API v3 with JWT authentication for Collections, Payouts, and Card
    Issuing.
  version: 3.0.0
  contact:
    name: FYATU Support
    url: https://fyatu.com
    email: support@fyatu.com
servers:
  - url: https://api.fyatu.com/api/v3
    description: Production
security: []
tags:
  - name: Authentication
    description: JWT token management endpoints
  - name: Account
    description: Business account, wallet, and address management
  - name: Collections
    description: Accept payments from customers via checkout sessions
  - name: Refunds
    description: Issue refunds for completed collections
  - name: Payouts
    description: Send money to Fyatu account holders
  - name: Cardholders
    description: Cardholder management for card issuing programs
  - name: Cards
    description: Issue, fund, freeze, and manage virtual cards
  - name: Webhooks
    description: Webhook configuration and management
paths:
  /webhooks/secret/regenerate:
    post:
      tags:
        - Webhooks
      summary: Regenerate Webhook Secret
      description: >-
        Generate a new webhook secret for signing webhook payloads. This
        immediately invalidates your previous secret.
      operationId: regenerateWebhookSecret
      responses:
        '200':
          description: Webhook secret regenerated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSecretResponse'
              example:
                success: true
                status: 200
                message: Webhook secret regenerated successfully
                data:
                  webhookSecret: whsec_x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6
                  regeneratedAt: '2026-01-15T10:30:00+00:00'
                  note: >-
                    Store this secret securely. It will not be shown again.
                    Update your webhook handler with this new secret.
                meta:
                  requestId: req_abc123xyz789
                  timestamp: '2026-01-15T10:30:00+00:00'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - BearerAuth: []
components:
  schemas:
    WebhookSecretResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
        data:
          type: object
          properties:
            webhookSecret:
              type: string
              description: Your new webhook secret. Store this securely!
            regeneratedAt:
              type: string
              format: date-time
            note:
              type: string
              description: Reminder to update your webhook handler
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      properties:
        requestId:
          type: string
          description: Unique request ID for tracking
          example: req_abc123def456
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the response
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status:
          type: integer
          example: 401
        message:
          type: string
          example: Invalid credentials
        error:
          $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/Meta'
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code for programmatic handling
          example: AUTH_INVALID_CREDENTIALS
        details:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
          description: Validation error details (for VALIDATION_ERROR)
    ValidationError:
      type: object
      properties:
        field:
          type: string
          description: Field that failed validation
          example: appId
        message:
          type: string
          description: Validation error message
          example: AppId is required
  responses:
    Unauthorized:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            status: 401
            message: Unable to identify business
            error:
              code: AUTH_TOKEN_INVALID
            meta:
              requestId: req_abc123
              timestamp: '2026-01-05T10:30:00+00:00'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from /auth/token

````