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

# Rotate the signing secret

> Rotate the signing secret for a webhook endpoint. Returns a **new** `signing_secret`
(prefixed `whsec_`) in plaintext — this is the only time it is shown, so store it
immediately.

Rotate the secret if the current one may have been exposed. After rotation, verify incoming
deliveries against the new secret.

### Example

```
POST /v1/notifications/webhooks/whr_01HXYZABC1234567890ABCDEFG/rotate-secret
```




## OpenAPI

````yaml /api-reference/openapi.json post /v1/notifications/webhooks/{id}/rotate-secret
openapi: 3.0.0
info:
  title: GlobalStack API
  version: 1.0.0
  description: >
    # Introduction


    GlobalStack API for cross-border payments powered by stablecoin rails.


    Getting started: authenticate with a Bearer token, make your first call to

    `GET /v1/currencies`, and explore.


    **Key operations:**


    - **Onramp** — convert external fiat into crypto credited to a wallet.

    - **Offramp** — convert crypto from a wallet into fiat delivered to a
    beneficiary.

    - **Conversion** — move value between two wallets belonging to the same
    customer.

    - **Transfer** — send crypto from a wallet to an external address.

    - **Deposit** — receive external crypto into a wallet via a deposit address.


    See the sections below for authentication, response shape, idempotency,

    references, metadata, and webhooks.


    ## Authentication


    All API requests require a Bearer token in the `Authorization` header:


    ```

    Authorization: Bearer gsa_sk_live_your_api_key

    ```


    API keys use the `gsa_sk_live_` prefix.


    API keys are scoped to a single merchant account. All resources created with

    a key belong to that merchant. Keep your keys secret — do not expose them in

    client-side code or public repositories.


    To rotate a key, generate a new one from your dashboard and update your

    integration before revoking the old key.


    ## API Response Shape


    Every response — success or failure — follows the same envelope:


    ```json

    {
      "status": true,
      "message": "Onramp created successfully",
      "code": "ok",
      "data": { },
      "meta": {
        "request_id": "req_01ABC...",
        "timestamp": "2026-04-22T02:00:00Z",
        "version": "1"
      }
    }

    ```


    **Fields:**


    - `status` (boolean) — whether the HTTP call succeeded. This is not the
      business status of the underlying resource.
    - `message` (string) — human-readable explanation for developers and logs.
      Do not show to end users.
    - `code` (string) — stable machine-readable result. `ok` on success, or an
      error code like `bad_request`.
    - `data` — the resource payload on success (object, array, or scalar).
    `null`
      on failure.
    - `meta` — request-scoped metadata, always present. Includes `request_id`
      (quote this in support tickets), `timestamp`, and `version`. On list
      endpoints, also includes `page`, `per_page`, `total`, `has_more`. On
      validation errors, includes `errors` array and `next_steps`.

    Error responses include `next_steps` in `meta` with an `action` string and a

    `docs_url` link:


    ```json

    {
      "status": false,
      "message": "Your request has validation errors.",
      "code": "bad_request",
      "data": null,
      "meta": {
        "request_id": "req_01ABC...",
        "timestamp": "2026-04-22T02:00:00Z",
        "version": "1",
        "errors": [
          { "field": "amount", "code": "required", "message": "Amount is required." }
        ],
        "next_steps": {
          "action": "Review the request and retry with corrected parameters.",
          "docs_url": "https://docs.globalstack.io/errors#bad_request"
        }
      }
    }

    ```


    ## Idempotency


    Pass an `Idempotency-Key` header on any create endpoint to make the request

    safely retryable:


    ```

    Idempotency-Key: your-unique-key-here

    ```


    **Rules:**


    - Same key + same body = returns the original response (no side effects).

    - Same key + different body = returns `idempotency_conflict` (409).

    - Keys are scoped to your merchant account.

    - Keys expire after 24 hours.


    Use idempotency keys for any operation that creates a resource or moves

    money. This protects against network retries, duplicate webhooks, and

    client-side retry loops.


    ## Rate Limits


    Requests over the rate limit are rejected with HTTP `429` and the error code

    `rate_limited`:


    ```json

    {
      "status": false,
      "message": "Too many requests. Slow down and retry shortly.",
      "code": "rate_limited"
    }

    ```


    **Money-movement writes** (creating transfers, offramps, conversions, or

    wallet operations) are limited **per merchant account** — the budget is

    shared across all of your API keys and dashboard sessions. Reads are not

    limited.


    On a `429`, back off and retry with jitter; for money movement, reuse the

    same `Idempotency-Key` so the retry stays safe.


    ## Reference


    Every money movement operation (onramp, offramp, conversion, transfer)

    accepts an optional `reference` field — a merchant-supplied identifier that

    is unique per merchant account.


    ```json

    {
      "reference": "INV-2026-001",
      "wallet_id": "wal_..."
    }

    ```


    If you omit `reference`, the API generates one automatically (prefixed

    `ref_`).


    References are unique per merchant — attempting to create two operations

    with the same reference returns the existing operation (same behavior as

    idempotency, but permanent and not time-limited).


    Use `reference` to correlate GlobalStack operations with your own system

    records (invoices, orders, payouts).


    ## Metadata


    Most create endpoints accept an optional `metadata` object — a flat set of

    string key/value pairs stored on the resource:


    ```json

    {
      "metadata": {
        "order_id": "ord_12345",
        "customer_email": "alice@example.com"
      }
    }

    ```


    Metadata is returned on every GET response and in webhook payloads. It is

    not used by GlobalStack for processing — it exists for your own

    record-keeping.


    Resources that accept metadata: customers, wallets, senders, beneficiaries,

    wallet credentials, deposit addresses, onramps, offramps, conversions, and

    transfers.


    ## Webhook Signatures


    Every webhook delivery is signed so you can verify it came from GlobalStack
    and

    was not tampered with in transit. Signatures follow the

    [Svix](https://docs.svix.com/receiving/verifying-payloads/how) standard, so
    you

    can verify them with any Svix library — or manually with the construction
    below.


    Each delivery carries three headers:


    ```

    svix-id: msg_2gT8sV...          # unique message id (the body's event_id,
    prefixed msg_)

    svix-timestamp: 1718960400      # unix seconds when the delivery was signed

    svix-signature: v1,g0hM9SsE...  # space-separated list of
    v1,<base64-signature>

    ```


    Your signing secret (prefixed `whsec_`) is returned in plaintext **exactly

    once** — when you create a webhook endpoint or rotate its secret. Store it

    securely; you cannot retrieve it again.


    **Verify with a Svix library (recommended):**


    ```python

    from svix.webhooks import Webhook


    wh = Webhook(signing_secret)                            # the whsec_...
    value

    payload = wh.verify(raw_request_body, request_headers)  # raises on a bad
    signature

    ```


    **Verify manually:**


    1. Build the signed content by joining the id, timestamp, and the **raw**
       request body with dots:

       ```
       signed_content = svix_id + "." + svix_timestamp + "." + raw_body
       ```

    2. Take your signing secret, drop the `whsec_` prefix, and base64-decode the
       remainder — those bytes are your HMAC key.

    3. Compute `base64(HMAC-SHA256(key, signed_content))`.


    4. The `svix-signature` header is a space-separated list of `v1,<signature>`
       entries (an endpoint can have more than one valid secret during a rotation).
       Compare your computed value against each entry's signature — the part after
       `v1,` — using a constant-time comparison, and accept if any matches.

    5. Reject deliveries whose `svix-timestamp` differs from your current time
    by
       more than a few minutes, to guard against replay.

    The body's `event_id` equals the `svix-id` without its `msg_` prefix, so you
    can

    use either to deduplicate redelivered events.


    ## Request IDs


    Every response carries an `X-Request-Id` header (also surfaced in

    `meta.request_id`). Include the value when reporting issues — it scopes

    backend logs to your specific request.


    You may also send your own `X-Request-Id` header. Values matching

    `^[A-Za-z0-9_-]{1,128}$` are honored verbatim; anything else is replaced
    with

    a generated id.


    ## Versioning


    Public endpoints are versioned under `/v1/`. Breaking changes ship under a
    new

    major version; additive changes (new fields, new endpoints) ship under the

    existing version.
  contact:
    name: Paystack Cross-Border
    url: https://globalstack.io
servers:
  - url: https://api.globalstack.io
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Supported Countries
  - name: Supported Currencies
  - name: Customers
  - name: Wallets
  - name: Beneficiaries
  - name: Quotes
  - name: Onramps
  - name: Offramps
  - name: Conversions
  - name: Transfers
  - name: Transactions
  - name: Notification Webhooks
  - name: Me
paths:
  /v1/notifications/webhooks/{id}/rotate-secret:
    post:
      tags:
        - Notification Webhooks
      summary: Rotate the signing secret
      description: >
        Rotate the signing secret for a webhook endpoint. Returns a **new**
        `signing_secret`

        (prefixed `whsec_`) in plaintext — this is the only time it is shown, so
        store it

        immediately.


        Rotate the secret if the current one may have been exposed. After
        rotation, verify incoming

        deliveries against the new secret.


        ### Example


        ```

        POST
        /v1/notifications/webhooks/whr_01HXYZABC1234567890ABCDEFG/rotate-secret

        ```
      operationId: NotificationWebhookController.rotateSecret
      parameters:
        - in: path
          name: id
          required: true
          schema:
            pattern: '[^\/#\?]+?'
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessEnvelope'
                  - type: object
                    required:
                      - data
                      - meta
                    properties:
                      message:
                        type: string
                        example: Signing secret rotated
                      data:
                        $ref: '#/components/schemas/RotateSecretResponse'
                      meta:
                        $ref: '#/components/schemas/ApiResponseMetaSchema'
          description: Signing secret rotated
        '400':
          description: The path id is not a valid `whr_…` identifier
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - invalid_input
        '401':
          description: Unauthorized — invalid or missing API key
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - authentication_failed
        '404':
          description: Webhook endpoint not found in this integration
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - not_found
        '500':
          description: >-
            The Notification Service was unreachable or returned an unexpected
            error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - external_service_unavailable
components:
  schemas:
    ApiSuccessEnvelope:
      properties:
        status:
          type: boolean
          enum:
            - true
          example: true
        message:
          type: string
          description: Human-readable summary
          example: Resource fetched successfully
        code:
          type: string
          enum:
            - ok
          example: ok
      type: object
      required:
        - status
        - message
        - code
    RotateSecretResponse:
      properties:
        id:
          type: string
          example: whr_01HXYZABC1234567890ABCDEFG
        signing_secret:
          type: string
          description: New signing secret (prefixed whsec_). Returned ONCE.
          example: whsec_K5x...base64...==
      type: object
      required:
        - id
        - signing_secret
    ApiResponseMetaSchema:
      properties:
        request_id:
          type: string
          description: ULID-prefixed identifier for this request
          example: req_01HXYZ4K5ABCDEFGHJKLMNPQRS
        timestamp:
          type: string
          format: date-time
          example: '2026-05-14T15:43:55.732Z'
        version:
          type: string
          description: Major API version parsed from /vN/
          example: '1'
      type: object
      required:
        - request_id
        - timestamp
        - version
    ApiErrorEnvelope:
      properties:
        status:
          type: boolean
          enum:
            - false
          example: false
        message:
          type: string
          description: Human-readable failure summary
          example: Resource not found
        code:
          type: string
          description: Stable error code for branching logic
          example: not_found
        data:
          type: object
          nullable: true
          example: null
        meta:
          $ref: '#/components/schemas/ApiErrorMetaSchema'
      type: object
      required:
        - status
        - message
        - code
        - data
        - meta
    ApiErrorMetaSchema:
      properties:
        next_steps:
          $ref: '#/components/schemas/NextStepsSchema'
        request_id:
          type: string
          description: ULID-prefixed identifier for this request
          example: req_01HXYZ4K5ABCDEFGHJKLMNPQRS
        timestamp:
          type: string
          format: date-time
          example: '2026-05-14T15:43:55.732Z'
        version:
          type: string
          description: Major API version parsed from /vN/
          example: '1'
      type: object
      required:
        - next_steps
        - request_id
        - timestamp
        - version
    NextStepsSchema:
      properties:
        action:
          type: string
          description: Suggested action for the caller
          example: Verify the resource identifier and retry.
        docs_url:
          type: string
          format: uri
          example: https://docs.globalstack.io/errors#not_found
      type: object
      required:
        - action
        - docs_url
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key issued during merchant onboarding.

````