Skip to main content

Rotate webhook endpoint secret

POST 
/api/v1/sdk/stores/:storeId/webhooks/:webhookId/rotate-secret

This endpoint generates a new webhook secret for signature verification. Use this to rotate secrets periodically for security or if a secret is compromised.

Authentication: Requires Private API Key (sk_*) with Administer permission

Rotation Behavior:
  • New secret is generated immediately
    • Old secret becomes invalid
    • All future webhook deliveries use new secret
    • New secret is only shown ONCE in response
    • Webhook continues receiving events without interruption
Response Data:
  • New webhook secret (string, 32+ characters)
    • Rotation timestamp (ISO 8601)
Use Cases:
  • Regular security secret rotation
    • Responding to secret compromise
    • Resetting forgotten secrets
    • Implementing secret rotation policies
Important Notes:
  • CRITICAL: Store the returned secret securely immediately
    • Secret cannot be retrieved again after this response
    • Update your webhook verification code with new secret
    • Old secret stops working immediately
    • Consider testing webhook after rotation to verify new secret works
Security Best Practices:
  • Rotate secrets every 90-180 days
    • Rotate immediately if secret may be compromised
    • Store secrets in secure environment variables or secret management
    • Never commit secrets to source control
Error Scenarios:
  • 404 NOT FOUND - Webhook or store not found (Error code: WEBHOOK_NOT_FOUND or STORE_NOT_FOUND)
    • 401 UNAUTHORIZED - Invalid or missing API key (Error code: INVALID_API_KEY)
    • 403 FORBIDDEN - Insufficient permissions (Error code: INSUFFICIENT_PERMISSIONS)

Request​

Responses​

Secret rotated successfully - STORE THE NEW SECRET IMMEDIATELY