---
title: "Rotate webhook signing secret"
description: "Returns a new signing secret; store it securely. The previous secret remains valid for 24 hours. Rotating again immediately discards the oldest secret, keeping only the new secret and its most recent predecessor. Identical retries recover the encrypted receipt for 15 minutes without rotating again. Disabled endpoints remain disabled."
language: en
canonical_url: "https://exac.mx/docs/en/api/workspace/credentials/rotate-webhook-endpoint-secret"
md_url: "https://exac.mx/docs/en/api/workspace/credentials/rotate-webhook-endpoint-secret.md"
---

# Rotate webhook signing secret

Returns a new signing secret; store it securely. The previous secret remains valid for 24 hours. Rotating again immediately discards the oldest secret, keeping only the new secret and its most recent predecessor. Identical retries recover the encrypted receipt for 15 minutes without rotating again. Disabled endpoints remain disabled.

## Request

`POST /v1/organization/webhook-endpoints/{endpointId}/rotate-secret`

- **Authorization:** Required permission: `apiKeys:manage`.

- **Environments:** Production and sandbox

- **Idempotency:** Required

## Canonical machine contract

This fragment is generated from the canonical operation and Zod contracts used by the route.

```json
{
  "method": "POST",
  "path": "/v1/organization/webhook-endpoints/{endpointId}/rotate-secret",
  "operation": {
    "operationId": "rotateWebhookEndpointSecret",
    "tags": [
      "Credentials"
    ],
    "summary": "Rotate webhook signing secret",
    "description": "Returns a new signing secret; store it securely. The previous secret remains valid for 24 hours. Rotating again immediately discards the oldest secret, keeping only the new secret and its most recent predecessor. Identical retries recover the encrypted receipt for 15 minutes without rotating again. Disabled endpoints remain disabled.",
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "parameters": [
      {
        "name": "endpointId",
        "in": "path",
        "required": true,
        "example": "example_endpoint_id",
        "schema": {
          "type": "string",
          "minLength": 1
        }
      },
      {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "example": "2f6b0e7a-5c1d-4e3a-9b8f-7d4a1c9e6b52",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "description": "Unique retry key for this exact operation. Reuse it only when retrying the same request."
      }
    ],
    "requestBody": {
      "required": false,
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          },
          "example": {}
        }
      }
    },
    "responses": {
      "200": {
        "description": "Operation completed.",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1
                    },
                    "url": {
                      "type": "string"
                    },
                    "description": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "eventTypes": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "string",
                            "const": "invoice.stamped"
                          },
                          {
                            "type": "string",
                            "const": "invoice.canceled"
                          },
                          {
                            "type": "string",
                            "const": "sat_sync.completed"
                          }
                        ]
                      }
                    },
                    "issuerRfcs": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "enabled",
                        "disabled"
                      ]
                    },
                    "disabledReason": {
                      "anyOf": [
                        {
                          "type": "string",
                          "enum": [
                            "manual",
                            "failing",
                            "gone"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "$ref": "#/components/schemas/Instant"
                    },
                    "updatedAt": {
                      "$ref": "#/components/schemas/Instant"
                    },
                    "secret": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "url",
                    "description",
                    "eventTypes",
                    "issuerRfcs",
                    "status",
                    "disabledReason",
                    "createdAt",
                    "updatedAt",
                    "secret"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "data"
              ],
              "additionalProperties": false
            }
          }
        }
      },
      "400": {
        "description": "Invalid request.\n\n`validation_error`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "401": {
        "description": "Missing or invalid credential.\n\n`unauthenticated`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "WWW-Authenticate": {
            "$ref": "#/components/headers/WWWAuthenticate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "402": {
        "description": "Insufficient prepaid balance or an unmet billing requirement.\n\n`payment_required`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "403": {
        "description": "The credential does not include the `apiKeys:manage` permission.\n\n`forbidden`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "WWW-Authenticate": {
            "$ref": "#/components/headers/WWWAuthenticate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "404": {
        "description": "Resource not found.\n\n`not_found`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "405": {
        "description": "Method not allowed.\n\n`method_not_allowed`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Allow": {
            "$ref": "#/components/headers/Allow"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "409": {
        "description": "State, environment, or idempotency conflict. Use error.code to determine recovery.\n\nPossible codes: `conflict`, `idempotency_conflict`, `operation_in_progress`, `recovery_required`, `migration_required`.",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "429": {
        "description": "Too many requests.\n\n`rate_limited`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "500": {
        "description": "Internal server error.\n\n`internal`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "503": {
        "description": "Service temporarily unavailable.\n\n`provider_unavailable`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    },
    "x-exac-environments": [
      "production",
      "sandbox"
    ],
    "x-exac-rate-limit": "sensitive"
  },
  "components": {
    "schemas": {
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ProgrammaticError"
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      },
      "ProgrammaticError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "validation_error",
              "unauthenticated",
              "forbidden",
              "payment_required",
              "not_found",
              "method_not_allowed",
              "conflict",
              "idempotency_conflict",
              "operation_in_progress",
              "recovery_required",
              "migration_required",
              "rate_limited",
              "provider_unavailable",
              "internal"
            ],
            "description": "Recommended action by code:\n\n- `validation_error` — Correct the request using error.message and, when present, details.issues paths and codes.\n- `unauthenticated` — Provide a valid API key or OAuth access token.\n- `forbidden` — Use a credential with the required permission.\n- `payment_required` — For details.reason = api_wallet_insufficient, add prepaid API/MCP credit using details.topUpUrl; balanceMinor is the balance in centavos. Otherwise review the billing requirement. Retry only after it is resolved.\n- `not_found` — Check the organization-scoped resource identifier.\n- `method_not_allowed` — Use the documented HTTP method.\n- `conflict` — Refresh the resource and resolve its current state.\n- `idempotency_conflict` — Use a new idempotency key for a changed request.\n- `operation_in_progress` — Wait for Retry-After, then repeat the exact request.\n- `recovery_required` — Do not retry automatically or change the idempotency key. Retrieve details.document.documentRef when present, verify the outcome, and contact support with Request-Id if it remains uncertain.\n- `migration_required` — Contact support to complete historical document migration; do not reissue the document.\n- `rate_limited` — Wait for Retry-After before retrying.\n- `provider_unavailable` — Retry only when the response marks the failure as retryable.\n- `internal` — A failed response does not prove that a write had no effect. Retry a read after backoff; retry a write only with its original idempotency key and unchanged request. Contact support with Request-Id if it persists."
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "object",
            "properties": {
              "document": {
                "type": "object",
                "properties": {
                  "documentRef": {
                    "$ref": "#/components/schemas/DocumentRef"
                  },
                  "editable": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "documentRef",
                  "editable"
                ],
                "additionalProperties": false
              },
              "issues": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "path": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "number"
                          }
                        ]
                      }
                    },
                    "message": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "path",
                    "message"
                  ],
                  "additionalProperties": false
                }
              },
              "retryable": {
                "type": "boolean"
              },
              "retryAfterSeconds": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 9007199254740991
              },
              "reason": {
                "type": "string"
              },
              "balanceMinor": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "topUpUrl": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "status": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "code",
          "message",
          "status"
        ],
        "additionalProperties": false
      },
      "DocumentRef": {
        "type": "string",
        "pattern": "^(invoice|withholding|sales_receipt|declaration|tax_compliance_opinion|sales_receipt_refund):.+$"
      },
      "Instant": {
        "type": "string",
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
      }
    }
  }
}
```

[OpenAPI 3.1](/openapi.json)

[Receive webhooks](/docs/en/webhooks)

[Event reference](/docs/en/webhooks/events)

Complete documentation: https://exac.mx/docs/en.md
Agent documentation index: https://exac.mx/docs/en/llms.txt
