Getting Started with SFTP

Wellhub supports SSH File Transfer Protocol (SFTP) for secure file exchanges. SFTP uses the Secure Shell (SSH) network protocol and public/private key pairs to enforce security.

General Information

Connection settings

• Host: sftp.clients.wellhub.com
• Port: 443

Limits

Authentication

To interact with the SFTP Server, you'll need to generate an SSH key on your computer, create an SFTP SSH key in the Wellhub Clients Portal, and register your SSH public key.

Generate an SSH Key

1. Open a Terminal and paste the text below, replacing the email with your email address.

ssh-keygen -t ed25519 -C "your_email@example.com"

Create an SFTP SSH Key

With an SSH key in hand, access the Portal using your Wellhub account.

The process for creating a new SFTP SSH key is the same, regardless of the type of management of your Wellhub account.

1. Select which entity you want to manage through the SFTP Server. The type of key depends on your selection:

2. Open the SFTP SSH keys page (sidebar menu, Settings, then SFTP) and click Create key.

3. In the Details step, give a name to the key in Key name and paste your SSH public key in Your public key. Then click Continue.

   To create the key pair, you can follow this guide: How to create SSH keys on macOS, Windows or Linux.

4. In the Key permissions step, choose the access level of the key for each area: No access, Read only or Read and write. Then click Create key.

Uploads require Read and write access. A key with Read only access can only download files.

5. The All set screen confirms that your new key is active and shows its Username. Click Copy to copy it, then click Done.

(Optional) Additional encryption (PGP)

If you wish, you can add additional PGP encryption for both uploads (such as eligibility and flexible benefits files) and downloads (such as payroll, reports and flexible benefits files). See Encryption for the full instructions.

Accessing the SFTP Server

Before connecting to the SFTP Server, you need the Username of an SFTP SSH key created in the Portal.

1. Go to the SFTP SSH keys page (sidebar menu, Settings, then SFTP) in the Portal.

2. Click the key you want to use to open its details.

3. In the drawer, click Copy next to Username, or copy it manually.

Connect to the SFTP Server

1. Open a terminal and run the command below, replacing your_username with the Username copied in the previous step.

sftp -P 443 -i ~/.ssh/id_ed25519 your_username@sftp.clients.wellhub.com

The flag -i ~/.ssh/id_ed25519 indicates the location of your SSH key's private key. Change the location if necessary.

2. Upon executing this command, you should see the welcome message from the SFTP Server.

SSH Key Algorithm Requirements

Wellhub's SFTP server supports modern SSH key algorithms. To maintain a secure connection environment, support for SSH algorithms that rely on SHA-1 is being deprecated and will eventually be discontinued.

Why SHA-1 is being deprecated

SHA-1 (Secure Hash Algorithm 1) is a cryptographic hash function historically used in SSH key and host key algorithms to verify authenticity. Over time, SHA-1 has become vulnerable to practical collision attacks — where two different inputs can produce the same hash value — which breaks a core security guarantee and makes it unsuitable for modern cryptographic use.

Continuing to rely on SHA-1-based algorithms exposes clients to:

• Potential impersonation or man-in-the-middle attacks if collisions are exploited
• Reduced trust in the integrity and authenticity of SSH connections
• Non-compliance with modern security recommendations and best practices

Supported SSH key algorithms

The SFTP server currently supports the following SSH public key algorithms:

Prioritize Ed25519 wherever possible — it provides strong security with smaller keys and better performance compared to traditional RSA-based algorithms.

Deprecation timeline

There is currently no fixed date set for the full removal of SHA-1-based SSH algorithms. However, the deprecation is in progress and support may be removed after an appropriate notice period.

Migration checklist

Use the following checklist to migrate away from SHA-1-based SSH algorithms:

1. Inventory existing keys and configurations: Identify all client systems and automated jobs that connect to the SFTP server, and list the SSH key types and algorithms they currently use.
2. Generate new Ed25519 keys: Create new Ed25519 key pairs for each client and store private keys securely (see Generate an SSH Key above).
3. Register new keys with the SFTP server: Add the new public keys to the Portal as described in Create an SFTP SSH Key.
4. Update client configurations: Configure SSH clients to prefer Ed25519 and SHA-2-based algorithms and to stop offering SHA-1-based algorithms during negotiation.
5. Test and phase out legacy keys: Validate connectivity using the new keys, update automation and documentation, then remove remaining SHA-1-dependent keys and algorithms from use.

File Exchange Frequency

The first production Eligibility File must be sent to Wellhub at least one week before the date that the Wellhub program will be announced to your company's employees.

For maintenance purposes, the Eligibility File must be sent to Wellhub at a minimum once a month. When integrating full files, sending it more than once a day is not recommended.

File Format Requirements

• It must include the configured eligible identifiers for the client/company tax ID — see Entity Types for details
• The header is mandatory, and needs to be in English for all countries
• The column order is not mandatory
• The column titles (attribute names) must be written exactly as indicated in the specification
• Unknown columns will be ignored
• The CSV can use any of the accepted separators: comma (,), semicolon (;), tab, and space
• CSV UTF-8 is the format supported
• National ID and Tax ID are validated as a mask; if they are wrong, an error is thrown
• Accepted file types: .xlsx, .csv → for SSH; .xlsx.pgp, .xlsx.gpg, .csv.pgp, .csv.gpg → if PGP is enabled

Note that even though .csv is supported, since this file format can be mutable, using .xlsx or encrypted files with PGP is highly recommended.

File Naming Convention

For production: your company name_Eligibility_mmddyyyy.csv

For test: your company name_Eligibility_Test_mmddyyyy.csv