/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Rotate Webhook Secret

Rotate Webhook Secret

Replace an outbound webhook endpoint's signing secret. The new secret is returned once.

POST/v1/projects/{projectId}/webhook-endpoints/{endpointId}/rotate-secretTry it
Session token

Replaces the signing secret of one outbound webhook endpoint — for example after the old one leaked. The new secret is returned once, in this response; Syntext stores only an encrypted copy and cannot show it again.

Note

Requires the admin or owner role. A member gets 403 forbidden ("Only workspace admins can manage webhook endpoints.") with details.requiredRole: "admin". Needs a session JWT — an API key gets 401.

Any plan. Needs the Webhooks add-on enabled; otherwise 403 addon_disabled.

Warning

The old secret stops working immediately — there is no overlap window. Every delivery from this moment, including replays of older deliveries, is signed with the new secret. Update your receiver right away, or accept both secrets there for a short while before you rotate.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID.
endpointId:stringpathRequired
The endpoint ID, from GET /webhook-endpoints.

No request body.

Response — 200 OK

A bare object, not wrapped in data, sent with Cache-Control: no-store:

Verify deliveries with the new secret as before: X-Syntext-Signature is sha256= followed by the hex HMAC-SHA256 of the raw body.

The rotation is recorded in the audit log as webhook.secret_rotated, with the endpoint URL. The secret itself is never logged.

Error Responses

401 Unauthorized

Missing, invalid or expired session JWT, or an API key.

403 Forbidden

•
forbidden — you are a member, not an admin or owner (details.requiredRole: "admin"), or not a member of the organization at all.
•
addon_disabled — the Webhooks add-on is not enabled for this project.

404 Not Found

not_found — the project does not exist, or there is no such endpoint in this project (including an ID that is not a UUID):

json
{
"error": {
"code": "not_found",
"message": "Webhook endpoint not found",
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}
Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/webhook-endpoints/2c7f1e9a-4b3d-4e8f-9a6c-1d0e5b7a3f28/rotate-secret \
-H "Authorization: Bearer $SYNTEXT_JWT"
Responseapplication/json
200OK
{
"endpoint": {
"id": "2c7f1e9a-4b3d-4e8f-9a6c-1d0e5b7a3f28",
"url": "https://hooks.example.com/syntext",
"events": ["build.completed", "build.failed"],
"active": true,
"createdAt": "2026-10-01T08:00:00.000Z"
},
"secret": "whsec_Q2x0b3dWc2VjcmV0U2hvd25Pbmx5T25jZQ"
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext