Adding Webfinger to this domain

Mastodon supports WebFinger to find a Mastodon account by searching for an email address. This is helpful if you’re looking for someone but you don’t know what server they’re in.


I recently migrated my Mastodon account to a different server. Mastodon does as much as possible to make this a smooth process. It allows you to move over your followers, followings, and some other things. It also allows you to redirect from the old account to the new one so people can follow you around. Great!

I figured this was a good time to add WebFinger to the mix. I can now be found by searching for, regardless of what server I’m in.

The Elk Mastodon app search interface. In the search box, the query returns a match for my account
My Mastodon profile is found in Elk

This works because Mastodon will perform a look up to, which contains the necessary information to resolve the account.


First, you must obtain the data contained by the WebFinger. In my case that meant visiting You can replace with your Mastodon server domain, and ggpsv with your Mastodon account name.

Next up, you must serve this data under ./well-known/webfinger. If you need to resolve a different Webfinger per searched email, you can do that too. Mastodon will send the email as a query parameter1.

In my case, I’m the only Mastodon user for this domain so I will respond to all requests with the same response. I’m using Hugo for this site, which means that I can add this as a static file.

I added the following configuration to my Hugo config.toml file:

staticDir = ['static']

This instructs Hugo to include static as a source of static files. Then, I created ./well-known/webfinger inside the static directory and then pasted the data that I received above.

My text editor with the WebFinger file open. In the sidebar, you can see this file exists under the 'static/.well-known' directory as 'webfinger'.

Because this site is completely static, all that is left for me is to build the site and upload it to my server. My web server will then return this file to any requests made for ./well-known/webfinger.

Edit 15 November 2023

It was brought up to me that it wasn’t clear whether the searched email matters or not. I’ve updated the post to address this.

  1. This is helpful in cases where there are multiple Mastodon users for a given domain. If so, your web server would need to look up the requested email and return the matching WebFinger or a 404. ↩︎