curl -X POST https://api.tracklysms.com/api/v2/webhooks/66b0f7c84a1d4b2e9c3a1f2e/rotate-secret \
-H "X-Api-Key: trk_your_api_key"
{
"webhook": {
"id": "66b0f7c84a1d4b2e9c3a1f2e",
"accountId": 1042,
"url": "https://hooks.bizinga.com/trackly",
"events": ["message.delivered", "message.failed"],
"active": true,
"effectiveActive": true,
"disabledReason": null,
"disabledAt": null,
"failureStartedAt": null,
"disableIncidentId": null,
"signingSecret": "new64hex...",
"previousSigningSecret": "old64hex...",
"signingSecretRotatedAt": "2026-07-26T16:00:00Z",
"createdAt": "2026-06-01T09:00:00Z",
"updatedAt": "2026-07-26T16:00:00Z"
},
"graceExpiresAt": "2026-07-27T16:00:00Z"
}
Webhooks (v2)
Rotate Signing Secret
Rotate an endpoint’s HMAC signing secret with a 24-hour grace window.
POST
/
v2
/
webhooks
/
{endpoint_id}
/
rotate-secret
curl -X POST https://api.tracklysms.com/api/v2/webhooks/66b0f7c84a1d4b2e9c3a1f2e/rotate-secret \
-H "X-Api-Key: trk_your_api_key"
{
"webhook": {
"id": "66b0f7c84a1d4b2e9c3a1f2e",
"accountId": 1042,
"url": "https://hooks.bizinga.com/trackly",
"events": ["message.delivered", "message.failed"],
"active": true,
"effectiveActive": true,
"disabledReason": null,
"disabledAt": null,
"failureStartedAt": null,
"disableIncidentId": null,
"signingSecret": "new64hex...",
"previousSigningSecret": "old64hex...",
"signingSecretRotatedAt": "2026-07-26T16:00:00Z",
"createdAt": "2026-06-01T09:00:00Z",
"updatedAt": "2026-07-26T16:00:00Z"
},
"graceExpiresAt": "2026-07-27T16:00:00Z"
}
Generates a new signing secret while keeping the old one valid for a 24-hour grace window. During the window, events carry the new signature in
The additive failure fields are staged and follow the endpoint response. Rotating the secret preserves destination failure state and retained history; use explicit re-enable after repairing and testing a disabled destination.
X-Trackly-Signature and the old one in X-Trackly-Signature-Prev, so you can roll the secret with zero missed events. See Webhook Signing.
Path Parameters
Examples
curl -X POST https://api.tracklysms.com/api/v2/webhooks/66b0f7c84a1d4b2e9c3a1f2e/rotate-secret \
-H "X-Api-Key: trk_your_api_key"
{
"webhook": {
"id": "66b0f7c84a1d4b2e9c3a1f2e",
"accountId": 1042,
"url": "https://hooks.bizinga.com/trackly",
"events": ["message.delivered", "message.failed"],
"active": true,
"effectiveActive": true,
"disabledReason": null,
"disabledAt": null,
"failureStartedAt": null,
"disableIncidentId": null,
"signingSecret": "new64hex...",
"previousSigningSecret": "old64hex...",
"signingSecretRotatedAt": "2026-07-26T16:00:00Z",
"createdAt": "2026-06-01T09:00:00Z",
"updatedAt": "2026-07-26T16:00:00Z"
},
"graceExpiresAt": "2026-07-27T16:00:00Z"
}
Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 404 | not_found | No endpoint with that id on the account. |
| 500 | internal_error | The rotation could not be completed; retry. |