Aura Logo
AuraAPI Docs
OpenapiV1WebhooksIdRotate secret

Rotate webhook secret

Generate a new signing secret for a webhook subscription.

How it works:

  1. A new secret is generated and becomes active immediately
  2. The old secret remains valid for 24 hours (grace period)
  3. During the grace period, deliveries include BOTH signatures (comma-separated in X-Aura-Signature)
  4. After the grace period, only the new secret is used

Response includes:

  • old_secret - Previous secret (for verifying in-flight deliveries)
  • new_secret - New secret (active immediately)
  • grace_period_ends_at - When the old secret expires

Recommended flow:

  1. Call this endpoint
  2. Update your verification code to accept both secrets
  3. After the grace period, remove old secret from your code
POST
/v1/webhooks/{id}/rotate-secret

Path Parameters

idstring

Webhook subscription ID (UUID)

Formatuuid

Response Body

application/json

application/json

curl -X POST "https://api.aura-app.ai/v1/webhooks/550e8400-e29b-41d4-a716-446655440000/rotate-secret"
{
  "success": true,
  "old_secret": "abc123...",
  "new_secret": "def456...",
  "rotated_at": "2026-03-21T08:00:00Z",
  "grace_period_ends_at": "2026-03-22T08:00:00Z"
}
{
  "success": false,
  "error": "Webhook subscription not found",
  "code": "WEBHOOK_NOT_FOUND"
}