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

# Rotate webhook secret

> Generate a new HMAC signing secret for the counter's webhook. The old secret is immediately invalidated — update your webhook handler before calling this.



## OpenAPI

````yaml /swagger.json post /merchant/api/v1/counters/{counterID}/rotate-secret
openapi: 3.0.3
info:
  title: Merchant API
  description: >-
    API for merchants to create and manage payment intents, POS counters, and
    transaction history in the FEX Payment Platform. Authentication uses
    Keycloak JWT (human merchants via password flow, POS terminals via client
    credentials).
  version: 1.0.0
  contact:
    name: FEX Payments Platform
servers:
  - url: http://api-sandbox.fexpayments.com
    description: Merchant API sandbox server
security: []
tags:
  - name: Payment Intents
    description: Create and manage payment intents
  - name: Counters
    description: >-
      POS terminal (counter) management — each counter has its own Keycloak
      client credentials and webhook endpoint
  - name: Admin
    description: Back-office endpoints restricted to platform admin role (`admin`)
  - name: Public
    description: Public endpoints accessible without authentication (for QR code payments)
  - name: Onboarding
    description: Merchant registration — requires platform admin JWT (realm role `admin`)
paths:
  /merchant/api/v1/counters/{counterID}/rotate-secret:
    post:
      tags:
        - Counters
      summary: Rotate webhook secret
      description: >-
        Generate a new HMAC signing secret for the counter's webhook. The old
        secret is immediately invalidated — update your webhook handler before
        calling this.
      parameters:
        - name: counterID
          in: path
          required: true
          description: Counter ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: New webhook secret generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  webhook_secret:
                    type: string
                    description: >-
                      New HMAC-SHA256 signing secret (64 hex chars). Store
                      securely — shown only once.
                    example: >-
                      a3f8c2e1d4b7a9f0e2c5b8d1a4f7c0e3d6b9a2f5c8e1d4b7a0f3c6e9d2b5a8f1
                  note:
                    type: string
                    example: >-
                      Update your webhook handler immediately — the old secret
                      is no longer valid.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - BearerAuth: []
components:
  responses:
    Unauthorized:
      description: Unauthorized — missing or invalid JWT
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: Unauthorized
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: Payment intent not found
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: Failed to create payment intent
  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Invalid request body
      required:
        - success
        - error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Keycloak JWT. Roles: `admin` (platform admin — can register merchants,
        act on behalf of any merchant), `merchant` (dashboard user — scoped to
        their own `merchant_id` via user attribute mapper), POS terminals use
        client credentials flow with `merchant_id` injected via protocol mapper.

````