Upload a well-known file

Updated

Upload a well-known file to your Webflow site.

You can add well-known files to your Webflow site in the Assets panel. The .well-known directory is a standardized location defined by the IETF where web servers can store specific, well-known metadata files that other systems or services can easily locate. It serves as a convention for exposing configuration, authentication, or service-related information for various protocols or use cases.

These files can define rules for:

  • Deep linking between your website and mobile apps
  • Security protocols and verification
  • Domain validation
  • Third-party service integration

How to upload .well-known files to your site

To add .well-known files to your site:

  1. Go to  the Assets panel
  2. Create a new folder in the Assets panel and name it "well-known"
  3. Upload your configuration files to this folder
  4. Publish your site

Important

If you don’t name the folder “well-known” the file upload won’t work.

To replace existing .well-known files in the Assets panel:

  1. Go to  the Assets panel
  2. Upload the configuration file to this folder with the same name as it is in the folder
  3. Publish your site

When you publish your site, Webflow automatically moves all files from the well-known folder to your site’s  /.well-known/ directory.

You can edit uploaded files as much as you want.

Supported file types and restrictions

File types can be either .json or .txt files. If you want to upload a well-known file without an extension, you can rename the extension ".noext" and we'll remove it from the file before serving it. 

The following restrictions apply to .well-known files: 

  • Maximum file size: 100KB
  • Maximum number of files: 30
  • Available on Business Site plans and higher
  • Won’t work on webflow.io 
  • Cache invalidation occurs on publish to ensure changes are reflected immediately

Note

Existing .well-known files (apple-app-site-association and apple-developer-merchantid-domain-association) on other Site plans will continue to work, but adding new files requires a Business Site plan or higher.

Valid and invalid file examples

  Examples
Valid file
  • Supported file type with valid extensions. 
  • Extension: .json or .txt
  • Name: my-file.json, my-file.txt, my-file.noext.json
Invalid file
  • File kind = "document."
  • Extension: .noext or without extension
  • Name: my-file or my-file.noext

Behavior for the .noext extension

  Behavior for .noext
With .noext

File names containing .noext will have the extension removed in the directory structure.

  • my-file.noext.json → https://website.com/.well-known/my-file
  • my-file.noext.txt → https://website.com/.well-known/my-file
  • my-file.noext → https://website.com/.well-known/my-file

This is valid only if you renamed the type of my-file.txt to my-file.noext, so the Kind=”Plain text Document."

In OSes like Windows, this might not work so we recommend keeping it my-file.noext.txt 
Without .noext

Files retain their extensions in the directory structure.

my-file.json → https://website.com/.well-known/my-file.json

my-file.txt → https://website.com/.well-known/my-file.txt

my-file → https://website.com/.well-known/my-file

Important

"File kind” and "Kind" reflect how macOS interprets the file based on metadata, UTIs, or file headers. It’s more robust because it can identify files even if the extension is missing or misleading. In other OSses, please make sure extension is set correctly.

The following restrictions apply to .well-known files: 

  • Maximum file size: 100KB
  • Maximum number of files: 30
  • Available on Business Site plans and higher
  • Won’t work on webflow.io 
  • Cache invalidation occurs on publish to ensure changes are reflected immediately

Note

Existing .well-known files (apple-app-site-association and apple-developer-merchantid-domain-association) on other Site plans will continue to work, but adding new files requires a Business Site plan or higher.

How to use .well-known files for security and verification

You can use .well-known files to implement security protocols on your site and verify domain ownership. They can provide support with:

  • security.txt — provides security policy information
  • Matrix server delegation
  • Domain verification for services such as Discord and Apple

Common use cases for .well-known files

One common use case for .well-known files is configuring deep linking between your website and iOS app using the apple-app-site-association file. To do so:

  1. Create your apple-app-site-association file in a JSON format
  2. Upload it to your “well-known” folder in the Assets panel

After publishing your site, the well-known URL will be available at: https://yoursite.com/.well-known/apple-app-site-association

Note

If you previously uploaded an apple-app-site-association file outside your well-known directory, uploading a new file to the “well-known” folder in the Assets panel will replace the existing configuration. That said, the old file will remain in the Assets panel for reference.

Best practices for using .well-known files

  • Keep your configuration files as small as possible
  • Use exactly the same filenames that match their intended purpose. It’s critical to name them exactly as per their use
  • Review your service provider's documentation for specific file requirements
  • Test your configuration files after publishing your site to ensure they're available

Uploading duplicate file content

We currently check for file content when determining duplicates during asset uploads. If two files have the same content, they are treated as identical, even if their names or extensions differ. For example, uploading myfile.txt and then renaming it to myfile.json and uploading again results in the original file being replaced.

To ensure both files are stored separately, you'll need to modify the content of one of the files before uploading. This behavior helps with optimization by avoiding duplicate content storage.

Related articles