# Rotate a webhook signing secret

`POST https://api.lingohub.com/v2/webhook-endpoints/{webhookEndpointId}/rotate-secret`

LingoHub API V2 (Beta) · [Webhooks](https://developers.lingohub.com/reference/v2/operations/tags/webhooks.md) · operation `rotateWebhookEndpointSecret`

Replaces the endpoint's signing secret and returns the new one. It is shown only in this response. The old secret stops working at once: everything sent from now on, including retries of earlier events, is signed with the new one, so update your receiver right away. If the response gets lost, rotate again. Send the ETag from GET as If-Match to make sure nobody changed the endpoint in between. Requires workspace-level API access management permission.

## Parameters

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `webhookEndpointId` | path | yes | string |  |
| `Idempotency-Key` | header | no | string | Optional unique key for best-effort duplicate suppression of this one-time response. The original successful response is returned to the caller but never retained in API log bodies or idempotent replays. Only an unresolv… |
| `If-Match` | header | no | string | Optional precondition. Send the quoted ETag from a GET of this resource. The mutation only runs if a strong tag matches the current representation, checked under the write lock. A comma-separated list is allowed; '*' req… |

## Example request

```sh
curl --request POST \
  --url https://api.lingohub.com/v2/webhook-endpoints/WEBHOOK_ENDPOINT_ID/rotate-secret \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Responses

- `200`: The endpoint with its new signing secret.
- `400`: 
- `401`: 
- `403`: 
- `404`: 
- `409`: An unresolved request returns `idempotency_outcome_unknown` without Retry-After; inspect the affected resource before starting a new operation. A recent request with the same Idempotency-Key is still being processed (`id…
- `412`: 
- `422`: The Idempotency-Key belongs to a different request (`idempotency_key_mismatch`).
- `429`: 
- `500`: 
- `503`: 

## OpenAPI definition

The complete definition of this operation, with every schema it references:

````json
{
  "openapi": "3.1.0",
  "info": {
    "title": "LingoHub API V2 (Beta)",
    "version": "2.0"
  },
  "servers": [
    {
      "url": "https://api.lingohub.com",
      "description": "LingoHub"
    }
  ],
  "tags": [
    {
      "name": "Webhooks",
      "description": "Receive LingoHub events at your own endpoint: manage endpoints and signing secrets, and inspect or redeliver deliveries."
    }
  ],
  "paths": {
    "/v2/webhook-endpoints/{webhookEndpointId}/rotate-secret": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Rotate a webhook signing secret",
        "description": "Replaces the endpoint's signing secret and returns the new one. It is shown only in this response. The old secret stops working at once: everything sent from now on, including retries of earlier events, is signed with the new one, so update your receiver right away. If the response gets lost, rotate again. Send the ETag from GET as If-Match to make sure nobody changed the endpoint in between. Requires workspace-level API access management permission.",
        "operationId": "rotateWebhookEndpointSecret",
        "parameters": [
          {
            "name": "webhookEndpointId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Public id composed of the resource type prefix and its UUID.",
              "pattern": "^whe_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Optional unique key for best-effort duplicate suppression of this one-time response. The original successful response is returned to the caller but never retained in API log bodies or idempotent replays. Only an unresolved reservation is retained for 24 hours by default; a matching retry returns 409 `idempotency_outcome_unknown` without repeating the operation or revealing its secret. A concurrent request returns 409 `idempotency_key_in_use`; a changed request returns 422 `idempotency_key_mismatch`. An unavailable reservation store returns 503 before execution. A 4xx rejection releases its reservation; interruption after execution or loss of the success response requires inspection and a deliberate new operation. Expiry of the retained reservation or server-side disabling removes protection; this is not durable exactly-once execution. Use the target GET to inspect current metadata and obtain its validator, then a new key only when intentionally rotating again.",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 255,
              "minLength": 1
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "description": "Optional precondition. Send the quoted ETag from a GET of this resource. The mutation only runs if a strong tag matches the current representation, checked under the write lock. A comma-separated list is allowed; '*' requires an existing representation. Weak tags never match. Omit this header for an unconditional write. For an action, use the ETag from GET of the target resource, without the action suffix. A stale tag returns 412; read the current state before retrying.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The endpoint with its new signing secret.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointWithSecret"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "An unresolved request returns `idempotency_outcome_unknown` without Retry-After; inspect the affected resource before starting a new operation. A recent request with the same Idempotency-Key is still being processed (`idempotency_key_in_use`); retry after the number of seconds in the `Retry-After` header.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait for an in-progress keyed request; absent for other conflicts.",
                "schema": {
                  "type": "integer",
                  "format": "int32"
                }
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "description": "The Idempotency-Key belongs to a different request (`idempotency_key_mismatch`).",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "headers": {
      "Cache-Control": {
        "description": "The one-time response must not be stored by HTTP caches.",
        "schema": {
          "type": "string",
          "enum": [
            "no-store"
          ]
        }
      },
      "RateLimit": {
        "description": "State of the rate-limit policy currently closest to rejection (IETF draft-ietf-httpapi-ratelimit-headers): the quoted policy name with `r` = requests remaining right now and `t` = seconds until the full quota is available again. Example: `\"api-key\";r=42;t=7`. Advisory: absent when the request fails authentication or the limiter state is momentarily unknown.",
        "schema": {
          "type": "string"
        }
      },
      "RateLimit-Policy": {
        "description": "The rate-limit policies applied to the request: each quoted policy name with `q` = sustained request quota per window of `w` seconds. Example: `\"api-key\";q=180;w=60, \"workspace\";q=600;w=60`. Advisory: absent when the request fails authentication or the limiter state is momentarily unknown.",
        "schema": {
          "type": "string"
        }
      },
      "Retry-After": {
        "description": "Seconds to wait before retrying.",
        "schema": {
          "type": "integer",
          "format": "int32"
        }
      }
    },
    "schemas": {
      "WebhookEndpointWithSecret": {
        "type": "object",
        "description": "A webhook endpoint together with its signing secret. Only the response that creates the endpoint or rotates its secret includes the secret.",
        "properties": {
          "object_type": {
            "type": "string",
            "description": "Always `WEBHOOK_ENDPOINT`.",
            "enum": [
              "WEBHOOK_ENDPOINT"
            ],
            "example": "WEBHOOK_ENDPOINT"
          },
          "id": {
            "type": "string",
            "description": "Unique identifier of the webhook endpoint.",
            "example": "whe_0197c8f2-5a6b-7cde-8f12-3456789abcde",
            "minLength": 1,
            "pattern": "^whe_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
          },
          "secret": {
            "type": "string",
            "description": "Signing secret of the endpoint's deliveries, shown only in this response. If it gets lost, rotate the secret.",
            "example": "whsec_example"
          },
          "url": {
            "type": "string",
            "description": "Public HTTPS address deliveries are sent to.",
            "example": "https://example.com/lingohub/webhooks"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Description of the endpoint; null when it has none.",
            "example": "Localization notifications"
          },
          "status": {
            "$ref": "#/components/schemas/WebhookEndpointStatus",
            "description": "ENABLED receives deliveries. DISABLED was switched off by hand. AUTO_DISABLED was switched off by LingoHub after 15 failed deliveries in a row. Both stay off until the endpoint is enabled.",
            "example": "ENABLED"
          },
          "event_types": {
            "type": "array",
            "description": "Subscribed events, as listed by listWebhookEventTypes; [\"*\"] subscribes to all events, including those added later.",
            "example": [
              "project.created"
            ],
            "items": {
              "type": "string",
              "example": "project.created"
            }
          },
          "stack_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Stack whose events the endpoint receives, its projects included. At most one of stack_id and project_id is set; neither means the whole workspace.",
            "pattern": "^stack_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
            "example": null
          },
          "project_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Project whose events the endpoint receives. At most one of stack_id and project_id is set; neither means the whole workspace.",
            "example": "pr_0197c8f2-5a6b-7cde-8f12-3456789abcde",
            "pattern": "^pr_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
          },
          "api_version": {
            "type": "string",
            "description": "Payload format the endpoint was created with.",
            "example": "2026-07-01"
          },
          "consecutive_failures": {
            "type": "integer",
            "format": "int32",
            "description": "Failed deliveries in a row since the last success; at 15 the endpoint is switched off.",
            "example": 0
          },
          "last_success_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When a delivery last succeeded; null if none has yet.",
            "example": "2026-09-29T10:00:00.123Z"
          },
          "last_failure_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When a delivery attempt last failed; null if none has yet.",
            "example": "2026-09-29T10:00:00.123Z"
          },
          "disabled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the endpoint was switched off; null while it is enabled.",
            "example": null
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the endpoint was created.",
            "example": "2026-09-29T10:00:00.123Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the endpoint was last changed.",
            "example": "2026-09-29T10:00:00.123Z"
          }
        },
        "required": [
          "api_version",
          "consecutive_failures",
          "created_at",
          "description",
          "disabled_at",
          "event_types",
          "id",
          "last_failure_at",
          "last_success_at",
          "object_type",
          "project_id",
          "secret",
          "stack_id",
          "status",
          "updated_at",
          "url"
        ]
      },
      "WebhookEndpointStatus": {
        "type": "string",
        "description": "Public webhook endpoint state.",
        "enum": [
          "ENABLED",
          "DISABLED",
          "AUTO_DISABLED"
        ]
      },
      "Error": {
        "type": "object",
        "description": "RFC 9457 problem details. `code` identifies the problem type (one per `type` URL); `errors` lists rejected fields or parameters; `required_permission` names the permission a 403 lacked.",
        "properties": {
          "type": {
            "type": "string",
            "description": "URL identifying the problem type and pointing to its documentation.",
            "example": "https://api.lingohub.com/errors/resource-not-found"
          },
          "title": {
            "type": "string",
            "description": "Short, constant summary of the problem type.",
            "example": "Resource not found"
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "description": "HTTP status code.",
            "example": 404
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation of this occurrence of the problem.",
            "example": "Resource with ID 'pr_0197c8f2-5a6b-7cde-8f12-3456789abcde' was not found."
          },
          "instance": {
            "type": "string",
            "description": "Path of the request that produced the problem.",
            "example": "/v2/projects/pr_0197c8f2-5a6b-7cde-8f12-3456789abcde"
          },
          "code": {
            "$ref": "#/components/schemas/ErrorCode",
            "description": "Machine-readable problem type.",
            "example": "resource_not_found"
          },
          "request_id": {
            "type": "string",
            "description": "Correlation id of the request, also returned in the `X-Request-ID` header. Quote it when contacting support.",
            "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
          },
          "errors": {
            "type": "array",
            "description": "Rejected fields or parameters. Present when the problem concerns specific fields or parameters.",
            "example": [
              {
                "detail": "must be at least 2 characters long",
                "pointer": "#/name",
                "parameter": "limit",
                "code": "minLength"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/FieldError"
            }
          },
          "required_permission": {
            "$ref": "#/components/schemas/RequiredPermission",
            "description": "The permission the API key lacks. Present on 403 responses."
          }
        },
        "required": [
          "code",
          "detail",
          "instance",
          "request_id",
          "status",
          "title",
          "type"
        ]
      },
      "ErrorCode": {
        "type": "string",
        "description": "Machine-readable problem type of a V2 error response. Each code has a fixed HTTP status and documentation at its `type` URL.",
        "enum": [
          "invalid_json",
          "invalid_parameter",
          "missing_parameter",
          "unknown_parameter",
          "invalid_filter",
          "invalid_cursor",
          "bad_request",
          "missing_api_key",
          "invalid_api_key",
          "expired_api_key",
          "revoked_api_key",
          "disabled_api_key",
          "insufficient_permissions",
          "resource_not_found",
          "route_not_found",
          "method_not_allowed",
          "not_acceptable",
          "precondition_failed",
          "content_too_large",
          "unsupported_media_type",
          "already_exists",
          "idempotency_outcome_unknown",
          "idempotency_key_in_use",
          "stack_not_empty",
          "branch_not_ready",
          "backup_not_ready",
          "backup_in_use",
          "default_branch_protected",
          "owner_membership_protected",
          "source_language_protected",
          "branch_limit_reached",
          "context_image_limit_reached",
          "automation_limit_reached",
          "translation_order_pending",
          "git_integration_not_configured",
          "branch_git_integration_not_configured",
          "git_integration_unauthorized",
          "conflict",
          "validation_failed",
          "idempotency_key_mismatch",
          "rate_limit_exceeded",
          "internal_error",
          "upstream_error",
          "service_unavailable",
          "upstream_timeout"
        ]
      },
      "FieldError": {
        "type": "object",
        "description": "A rejected field or parameter. `pointer` locates a body field (RFC 6901 JSON Pointer), `parameter` a query, path or header parameter or a field of a multipart upload; both are set for a position inside a JSON-valued parameter such as `filter`.",
        "properties": {
          "detail": {
            "type": "string",
            "description": "Human-readable description of the problem.",
            "example": "must be at least 2 characters long"
          },
          "pointer": {
            "type": [
              "string",
              "null"
            ],
            "description": "JSON Pointer to the offending body field, or to the position inside a JSON-valued parameter.",
            "example": "#/name"
          },
          "parameter": {
            "type": [
              "string",
              "null"
            ],
            "description": "Name of the offending query, path or header parameter, or of the multipart form field.",
            "example": "limit"
          },
          "code": {
            "$ref": "#/components/schemas/FieldErrorCode",
            "description": "Why the field or parameter was rejected.",
            "example": "minLength"
          }
        },
        "required": [
          "code",
          "detail",
          "parameter",
          "pointer"
        ]
      },
      "FieldErrorCode": {
        "type": "string",
        "description": "Why a field or parameter was rejected: the JSON Schema keyword of the violated rule, or one of the documented rules that no schema can express.",
        "enum": [
          "required",
          "type",
          "enum",
          "minLength",
          "maxLength",
          "minimum",
          "maximum",
          "pattern",
          "format",
          "additionalProperties",
          "minItems",
          "maxItems",
          "uniqueItems",
          "already_exists",
          "not_found",
          "not_supported",
          "unsupported_file_extension",
          "file_too_large",
          "file_empty",
          "invalid_archive",
          "empty_archive"
        ]
      },
      "RequiredPermission": {
        "type": "object",
        "description": "The permission the API key lacks, in the vocabulary of the API key permission settings.",
        "properties": {
          "scope": {
            "$ref": "#/components/schemas/PermissionScope",
            "description": "Where the permission applies.",
            "example": "STACK"
          },
          "target": {
            "$ref": "#/components/schemas/PermissionTarget",
            "description": "The area the permission governs.",
            "example": "SETTINGS"
          },
          "level": {
            "$ref": "#/components/schemas/PermissionLevel",
            "description": "The access level required.",
            "example": "MANAGE"
          }
        },
        "required": [
          "level",
          "scope",
          "target"
        ]
      },
      "PermissionScope": {
        "type": "string",
        "description": "Where a permission applies: `WORKSPACE` permissions cover workspace-level resources, `STACK` permissions the resources of a stack (its projects, branches, resources, languages, ...).",
        "enum": [
          "WORKSPACE",
          "STACK"
        ]
      },
      "PermissionTarget": {
        "type": "string",
        "description": "The area a permission governs.",
        "enum": [
          "GENERAL",
          "BILLING_SUBSCRIPTION",
          "WORKSPACES",
          "MEMBERS",
          "PLUGINS_INTEGRATIONS",
          "LOGS",
          "API_ACCESS",
          "STACKS",
          "TRANSLATION_ORDERS",
          "WORK_REPORTS",
          "STYLE_GUIDES",
          "GLOSSARIES",
          "TRANSLATION_MEMORIES",
          "LABELS",
          "AI_TRANSLATION",
          "QUICK_TRANSLATIONS",
          "SETTINGS",
          "ACTIVITIES",
          "RESOURCES",
          "CONTEXT_IMAGES",
          "LANGUAGES",
          "SEGMENT_KEYS",
          "SEGMENTS",
          "SEGMENT_TEXTS"
        ]
      },
      "PermissionLevel": {
        "type": "string",
        "description": "Access level of a permission: `MANAGE` includes `WRITE` and `VIEW`.",
        "enum": [
          "NO_ACCESS",
          "VIEW",
          "WRITE",
          "MANAGE"
        ]
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request is malformed: an unknown or invalid query parameter, an invalid id in the path, or a body that is not valid JSON. `code` names the problem, `errors` the parameter or field.",
        "headers": {
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Invalid or missing API key.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Insufficient permissions.",
        "headers": {
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "The resource does not exist, or the API key cannot see it.",
        "headers": {
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "PreconditionFailed": {
        "description": "The current representation does not match If-Match (`precondition_failed`). No change was applied.",
        "headers": {
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "The API rate limit was exceeded. Wait for the number of seconds given in the Retry-After header, then retry.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "An unexpected internal server error occurred.",
        "headers": {
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The service is temporarily unavailable. Retry after the number of seconds in the Retry-After header.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "description": "API key authentication. Create API keys in your LingoHub workspace settings. Keys use the `lh-api_` prefix. Pass the full key as the Bearer token.",
        "scheme": "bearer"
      }
    }
  }
}
````
