Webmentions

Don’t worry. Webmentions aren’t that complicated!

The Setting

Let’s imagine there are two bloggers in the world. Of course, they read each other’s blogs.

One day, Blogger A writes a post about quantum mechanics. Blogger B reads the post and wants to add something. Too much for just a comment, she thinks, and instead writes her own blog post. In that post, she links to Blogger A’s article.

Both blogs support Webmentions, so Blogger B’s follow-up post is automatically linked under Blogger A’s post once it’s published. Magic ✨

The Basic Principle

Sorry to burst your bubble, but there’s no magic here. Nor are there entangled quantum particles involved—just three URL requests.

As soon as Blogger B publishes her post, her Content Management System (CMS) scans the text. It collects all URLs from the post and finds the one pointing to Blogger A’s article.

The CMS takes that URL and requests it. It looks for a specific piece of information hidden in the page’s header—not visible on the site itself. Inside the header, there’s another URL: the so-called Webmention endpoint.

This endpoint is like a communication interface for Webmentions. You can send certain data there, and the endpoint processes it. It might look like this:

<link rel="webmention" href="https://maurice-renck.de/indieconnector/webmention">

That’s the endpoint on my website. If you check the source code, you’ll find it there.

With this HTML tag, I declare where Webmentions should be sent if someone wants to send me one.

So, Blogger B’s CMS calls Blogger A’s page, finds this information, and retrieves the Webmention endpoint URL. Then it calls that endpoint.

This request contains two pieces of information the endpoint needs in order to work:

1. A source URL (the blog post from Blogger B)
2. A target URL (the blog post from Blogger A)

With the source URL, Blogger B says: “I published something at this URL, and I mentioned you there.”

With the target URL, Blogger B says: “Here’s the post of yours that I mentioned.”

Blogger A now has all the necessary information, and her CMS can do whatever it wants with it—for example, simply show under her post that the source URL mentioned it.

A Bit More Context

Of course, it would be nicer if not just a link showed up, but some additional information: Blogger A might want to display the post’s title, the author, or even a short excerpt.

For that, a third URL request is needed.

Let’s recap: Blogger B just called Blogger A’s Webmention endpoint and sent info about her post.

Now Blogger A’s CMS takes that source URL and requests it. It scans the blog post for useful details—like the title, author, and other metadata—just as if we were loading the page in a browser.

Once found, these details are stored alongside the source URL and can then be displayed under Blogger A’s article.

In Short

That completes the communication. Let’s summarize the three requests:

1. Blog B asks Blog A: “Where should I send my Webmention?”
2. Blog B sends Blog A two URLs: the source and the target
3. Blog A visits the source and fetches the information it wants to show

Not so complicated, right?
When I first started looking into this, this simple sequence was what tripped me up: “It can’t really be that easy?” But essentially, it is.

A Bit More Complicated?

Of course, things aren’t always that simple. There are edge cases, which is why it’s usually a good idea to use an existing plugin rather than building everything from scratch.

For example, a site might send an update. Maybe something in the text or title changed. Blogger B’s CMS would then notify Blogger A of these changes—again by sending both URLs. Blogger A’s CMS has to detect that this is an update and decide how to handle it.

Or Blogger B might decide to delete the post altogether. The CMS deletes the page and, as a final action, sends another Webmention to Blogger A. Ideally, Blogger A’s CMS then checks the source URL, finds that the page is gone, and removes the reference from her own site.

Providing Information

Fetching the title of a blog post might still be straightforward. But what about the author’s name, the publication date, or even an excerpt of the text?

Every website is structured differently. The HTML varies, and the needed information won’t always be in the same place. Blogger B’s CMS wouldn’t know what’s what. If it relied on a fixed pattern, it might work on Blogger A’s site but not on Blogger C’s.

That’s why we should use microformats on our sites. These are specific class names that follow a structure. By assigning one of these classes, we can, for example, make it clear: “This is the author of the post.”

We can even go further and add classes to describe the type of Webmention: is it a mention, a like, a bookmark? There are special class names for all of that.

But here’s the catch: just because we provide this information doesn’t mean the recipient will actually read it.

Microformats are a big topic on their own, and I’ve written about them here.

Implementation

I hope it’s clear by now that Webmentions aren’t all that complicated. If you want to implement them yourself, you just need to make sure those three requests work smoothly, that the received data is stored somewhere, and that it’s displayed.

Because of possible tricky edge cases, I recommend using a plugin if your CMS has one available. I wrote one for Kirby, the IndieConnector.

If you’d like, you can test your Webmention by linking to this very post.