> ## Documentation Index > Fetch the complete documentation index at: https://docs.paywise.de/llms.txt > Use this file to discover all available pages before exploring further. # Rotate webhook secret > Company-scoped webhook endpoint management. ## OpenAPI ````yaml /api-docs/case-management-api/openapi.json post /v2/webhooks/{id}/rotate-secret/ openapi: 3.0.3 info: description: >- Submit orders and manage their complete lifecycle through the current API at the `/v2/` HTTP path. title: paywise Case Management API version: current servers: - description: Production environment url: https://api.paywise.de - description: Sandbox environment url: https://api-sandbox.paywise.de security: [] tags: - description: Submit orders and manage them until acceptance. name: Orders - description: Stable claim resources and their current relationships. name: Claims - description: 'Accepted cases: state, published history and documents.' name: Mandates - description: Debtor master data reused across orders. name: Debtors - description: Payments reported by you and booked by paywise. name: Payments - description: Files attached to claims and other resources. name: Documents - description: Collective statements (Sammelabrechnungen). name: Statements - description: Per-case statements (Aktenabrechnungen). name: Single mandate statements - description: Webhook endpoints and their signing secrets. name: Webhooks - description: Delivery log and redelivery of webhook events. name: Webhook deliveries - description: Ordered feed of the events webhooks deliver. name: Events - description: Reference catalog of legal forms. name: Legal forms - description: The authenticated credential and its context. name: Info - description: Rate-limit headroom of the credential. name: Usage - description: Availability of the API. name: Health externalDocs: url: https://docs.paywise.de/api-docs/case-management-api/introduction paths: /v2/webhooks/{id}/rotate-secret/: post: tags: - Webhooks summary: Rotate webhook secret description: Company-scoped webhook endpoint management. operationId: rotate-webhook-secret parameters: - description: >- Required when a Partner key calls the Case Management API; rejected for direct Case keys. Contains the entitled paywise company UUID. in: header name: X-On-Behalf-Of-Company schema: format: uuid type: string - description: UUID of the webhook subscription in this request. in: path name: id required: true schema: format: uuid type: string - description: >- Required client-supplied command key scoped to the selected Case company or Partner owner, method, operation and path. An exact retry replays the original response while it is retained, including after credential rotation or replacement. Current permissions are required. in: header name: Idempotency-Key required: true schema: maxLength: 255 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/CaseWebhookWithSecret' description: '' headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '400': content: application/json: examples: validation-error: value: code: validation_error detail: The request contains invalid data. errors: - code: invalid field: claims[0].due_date message: Due date must not precede the document date. schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '401': content: application/json: examples: authentication-error: value: code: not_authenticated detail: Authentication credentials were not provided. schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '404': content: application/json: examples: not-found-error: value: code: not_found detail: The requested resource was not found. schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '409': content: application/json: examples: conflict-error: value: code: conflict detail: The resource changed state and cannot accept this command. schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '429': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string Retry-After: description: Integer seconds to wait before retrying a throttled request. schema: minimum: 1 type: integer X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string security: - caseBearerAuth: [] - partnerBearerAuth: [] components: schemas: CaseWebhookWithSecret: description: Create / rotate-secret response — surfaces `secret_key` exactly once. properties: auto_disabled: description: >- `true` when the endpoint was disabled automatically after reaching `max_consecutive_failures`; re-enable it with `enabled: true` once the destination is fixed. readOnly: true type: boolean consecutive_failures: description: >- Consecutive deliveries that reached terminal failure. Individual retry attempts do not increment this counter; a successful delivery resets it. readOnly: true type: integer contract_version: allOf: - $ref: '#/components/schemas/ContractVersionEnum' description: >- Payload/signature contract of this endpoint. Endpoints created via this API are always `v2`; `v1` marks a legacy subscription that still receives v1 payloads and must be recreated to migrate. * `v1` - Legacy v1 * `v2` - Version 2 readOnly: true created_at: description: Time at which the webhook subscription was created. format: date-time readOnly: true type: string description: description: Optional single-line label for this webhook. maxLength: 255 type: string enabled: description: >- Whether deliveries are attempted. Re-enabling an endpoint resets its consecutive failure counter. type: boolean events: description: >- Current public event subscriptions for this endpoint. `["*"]` subscribes to all public events; otherwise the list contains the subscribed event types. items: $ref: '#/components/schemas/CaseWebhookSubscriptionEventEnum' type: array id: description: Stable identifier for this resource. format: uuid readOnly: true type: string last_failure_at: description: >- Time of the most recent terminal delivery failure since the last successful delivery; null after a successful delivery or when no failure has been recorded. format: date-time nullable: true readOnly: true type: string max_consecutive_failures: description: >- Automatically disables the endpoint when this many consecutive deliveries reach terminal failure. Retry attempts within one delivery do not each count. maximum: 1000 minimum: 1 type: integer secret_key: description: >- Signing secret shown once on creation or rotation. Store it to verify webhook signatures; list, retrieve, and idempotent replay responses omit it. readOnly: true type: string updated_at: description: Time at which the webhook subscription was last updated. format: date-time readOnly: true type: string url: description: >- Publicly reachable HTTPS URL for webhook notifications. Must be unique among this company’s v2 endpoints; duplicate checks normalize the scheme, host, and default port. format: uri maxLength: 2048 type: string required: - auto_disabled - consecutive_failures - contract_version - created_at - id - last_failure_at - updated_at - url type: object Error: properties: code: description: Machine-readable error category. type: string detail: description: Short human-readable summary of the error. type: string errors: description: Field-level validation errors, when applicable. items: $ref: '#/components/schemas/ErrorItem' type: array required: - detail - code type: object ContractVersionEnum: description: |- * `v1` - Legacy v1 * `v2` - Version 2 enum: - v1 - v2 type: string CaseWebhookSubscriptionEventEnum: description: >- * `*` - * * `order.submitted` - order.submitted * `order.withdrawn` - order.withdrawn * `order.rejected` - order.rejected * `order.accepted` - order.accepted * `order.expired` - order.expired * `mandate.created` - mandate.created * `mandate.state.changed` - mandate.state.changed * `mandate.status_update.published` - mandate.status_update.published * `mandate.balance_updated` - mandate.balance_updated * `order.message.created` - order.message.created * `mandate.message.created` - mandate.message.created * `request_to_client.created` - request_to_client.created * `request_to_client.answered` - request_to_client.answered * `payment.reported` - payment.reported * `statement.published` - statement.published * `statement.cancelled` - statement.cancelled * `single_mandate_statement.published` - single_mandate_statement.published * `single_mandate_statement.cancelled` - single_mandate_statement.cancelled * `invoice.created` - invoice.created * `invoice.paid` - invoice.paid * `invoice.cancelled` - invoice.cancelled * `invoice.written_off` - invoice.written_off * `dunning.level_advanced` - dunning.level_advanced * `dunning.handed_to_collection` - dunning.handed_to_collection enum: - '*' - order.submitted - order.withdrawn - order.rejected - order.accepted - order.expired - mandate.created - mandate.state.changed - mandate.status_update.published - mandate.balance_updated - order.message.created - mandate.message.created - request_to_client.created - request_to_client.answered - payment.reported - statement.published - statement.cancelled - single_mandate_statement.published - single_mandate_statement.cancelled - invoice.created - invoice.paid - invoice.cancelled - invoice.written_off - dunning.level_advanced - dunning.handed_to_collection type: string ErrorItem: properties: code: description: Machine-readable field error code. type: string field: description: >- Path to the field that caused the error, using dots for objects and brackets for list indexes, for example `claims[0].amount`; null for an error without a field path. nullable: true type: string message: description: Human-readable explanation of the field error. type: string required: - field - code - message type: object securitySchemes: caseBearerAuth: description: >- Company-bound Case Management API key — the standard credential for this API. scheme: bearer type: http partnerBearerAuth: description: >- Partner API key acting for one entitled company; every Case request must then also carry the X-On-Behalf-Of-Company header. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.