Overview
Generates a new signing secret for a webhook subscription and returns it. The previous secret is immediately invalidated.
Use this endpoint if your secret is compromised, as part of a regular rotation policy, or after onboarding a new team member who should not have access to the old secret.
After rotation, all future webhook deliveries will be signed with the new secret. You must update your verification logic immediately after receiving the new secret — there is no grace period during which both secrets are valid simultaneously.
Endpoint
POST /partners/webhooks/subscriptions/:id/rotate-secret
Authentication
Requires a valid API Key with the partner_webhooks_manage permission.
Path Parameters
| Parameter | Type | Required | Description |
|---|
id | UUID | Yes | The subscription ID. |
Example Request
curl -X POST "https://apiv3.thecleanlife.dev/v1/partners/webhooks/subscriptions/gggggggg-0000-0000-0000-000000000001/rotate-secret" \
-H "x-api-key: YOUR_API_KEY"
Success Response
HTTP Status: 200 OK
{
"success": true,
"data": {
"id": "gggggggg-0000-0000-0000-000000000001",
"secret": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e"
}
}
Critical: Save the new secret immediately. This is the only time it will be returned.
Error Responses
| HTTP Status | Code | Description |
|---|
401 | UNAUTHORIZED | Missing or invalid API key |
403 | FORBIDDEN | Missing partner_webhooks_manage permission |
404 | RESOURCE_NOT_FOUND | Subscription not found |
Rotation Strategy
To rotate with zero downtime:
- Call this endpoint to get the new secret.
- Update your environment variable / secrets manager with the new value.
- Deploy the new configuration.
- Verify a test webhook event is processed successfully.
Because there is no dual-secret window, it is recommended to:
- Do this rotation during low-traffic periods.
- Have monitoring in place to detect signature verification failures immediately after rotation.
