> ## Documentation Index > Fetch the complete documentation index at: https://platform.doodocs.kz/llms.txt > Use this file to discover all available pages before exploring further. # Rotate Webhook Endpoint Secret > Issues a new signing secret and returns it once. The previous secret keeps working for grace_seconds so a receiver can switch over without dropping deliveries: during that window every delivery carries the new signature in Doodocs-Signature and the old one in Doodocs-Signature-Previous. Accept either header until you have deployed the new secret, then accept only Doodocs-Signature. Exactly one previous secret is kept, so a rotation is refused while another one's window is still open. Wait for that window to close, or pass grace_seconds: 0 to cut over immediately, which also revokes a leaked secret at once. Required scope: webhooks:manage Error Codes: - WEBHOOK_NOT_FOUND: No such endpoint in the caller's tenant. - DEVELOPER.WEBHOOK_ROTATION_IN_PROGRESS: A previous secret is still inside its grace window. ## OpenAPI ````yaml /api-reference/openapi.yaml post /developer/v1/webhook_endpoints/{id}/_rotate_secret openapi: 3.0.3 info: description: >- Публичный Developer API Doodocs People. Аутентификация — заголовок X-API-Key. title: Doodocs People API version: 1.0.0 servers: - description: Production url: https://app.doodocs.kz/api security: - ApiKeyAuth: [] tags: - description: ApiKeyService exposes Developer API key utilities. name: ApiKeyService - description: >- DocumentService is the public Developer API for documents: reading, creating, downloading, routing, and signing. Authentication: X-API-Key. Every call runs as the key's owner within the key's tenant — the owner's document permissions decide what is visible and which actions are allowed, exactly as they would in the web app. Fields that carry personal data of other participants (names, IIN, positions) are never exposed; participants are identified by id only. Typical flow: discover a template with ListDocumentTemplates / GetDocumentTemplate (to learn its variable_schema), create a draft with CreateDocument, set its route with SetDocumentRoute, launch it with SendDocument, then apply signatures with SignDocument as slots become active. To circulate a document produced elsewhere, upload it with FileService and pass the confirmed file_id to CreateDocument instead of a template. name: DocumentService - description: |- EmployeeService is the public Developer API for reading employees. Authentication: X-API-Key. The key's tenant and the key owner's data scope determine which employees and fields are visible; sensitive fields the caller may not view are omitted and listed in `redacted_fields`. name: EmployeeService - description: |- FileService uploads the files documents are created from. Authentication: X-API-Key. An upload belongs to the key's owner, and only their key can attach it to a document. Flow: CreateFileUpload reserves the file and returns a presigned POST form, the client sends the bytes straight to storage, ConfirmFileUpload marks the upload complete, and CreateDocument attaches it by id. name: FileService - description: IngestService accepts batches of external records into the tenant. name: IngestService - name: LoginService - description: |- WebhookService lets a tenant manage subscriptions to Developer API events. Authentication: X-API-Key with the webhooks:manage scope. name: WebhookService paths: /developer/v1/webhook_endpoints/{id}/_rotate_secret: post: tags: - WebhookService summary: Rotate Webhook Endpoint Secret description: >- Issues a new signing secret and returns it once. The previous secret keeps working for grace_seconds so a receiver can switch over without dropping deliveries: during that window every delivery carries the new signature in Doodocs-Signature and the old one in Doodocs-Signature-Previous. Accept either header until you have deployed the new secret, then accept only Doodocs-Signature. Exactly one previous secret is kept, so a rotation is refused while another one's window is still open. Wait for that window to close, or pass grace_seconds: 0 to cut over immediately, which also revokes a leaked secret at once. Required scope: webhooks:manage Error Codes: - WEBHOOK_NOT_FOUND: No such endpoint in the caller's tenant. - DEVELOPER.WEBHOOK_ROTATION_IN_PROGRESS: A previous secret is still inside its grace window. operationId: WebhookService_RotateWebhookEndpointSecret parameters: - description: Endpoint id (UUID) whose secret is rotated. in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RotateWebhookEndpointSecretRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/RotateWebhookEndpointSecretResponse' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Status' description: Default error response components: schemas: RotateWebhookEndpointSecretRequest: properties: grace_seconds: description: >- How long the previous secret keeps signing deliveries, in seconds. Omit for the 86400-second (24 hour) default. Pass 0 to drop the previous secret at once — the right choice when it leaked, because a graceful rotation leaves a leaked secret able to forge deliveries for the whole window. format: int32 type: integer id: description: Endpoint id (UUID) whose secret is rotated. type: string required: - id type: object RotateWebhookEndpointSecretResponse: properties: endpoint: allOf: - $ref: '#/components/schemas/WebhookEndpoint' description: >- The endpoint after rotation; previous_secret_expires_at bounds the window in which the old secret still signs deliveries. readOnly: true secret: description: The new signing secret. Shown once — store it now. readOnly: true type: string type: object Status: description: >- The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). properties: code: description: >- The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. format: int32 type: integer details: description: >- A list of messages that carry the error details. There is a common set of message types for APIs to use. items: $ref: '#/components/schemas/GoogleProtobufAny' type: array message: description: >- A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. type: string type: object WebhookEndpoint: description: WebhookEndpoint is a subscription that receives signed event deliveries. properties: active: description: >- Whether deliveries are being sent. Becomes false after repeated delivery failures (auto-disable) or a manual disable; while false, new events are not queued for this endpoint. readOnly: true type: boolean create_time: description: When the endpoint was created. format: date-time readOnly: true type: string disabled_reason: description: >- Set when the endpoint was auto-disabled after repeated delivery failures. readOnly: true type: string event_types: description: Event types delivered to this endpoint. items: type: string readOnly: true type: array id: description: Endpoint id (UUID). readOnly: true type: string last_success_at: description: When the last successful delivery happened. format: date-time readOnly: true type: string previous_secret_expires_at: description: >- While set and in the future, the previously issued secret still signs deliveries in the Doodocs-Signature-Previous header. Empty when no rotation is in flight. format: date-time readOnly: true type: string update_time: description: When the endpoint was last changed. format: date-time readOnly: true type: string url: description: Delivery target URL (https). readOnly: true type: string type: object GoogleProtobufAny: additionalProperties: true description: >- Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. properties: '@type': description: The type of the serialized message. type: string type: object securitySchemes: ApiKeyAuth: in: header name: X-API-Key type: apiKey ````