Webmention
Introduction, examples, and resources

This page collects information and resources regarding Webmention, a core technology of the IndieWeb movement. Webmention presents a simple protocol that enables surprisingly rich communication among independent websites.

• Preface
• Introduction
  • What is Webmention?
  • How webmentions work
  • Webmentions and Microformats
• Examples
• Resources
  • Learning about Webmention (and Microformats)
  • Using Webmention
  • Developing with Webmention

Preface

I created this page a couple of years after beginning to study and use Webmention. I intend it to supplement IndieWeb’s own pages on the subject, which tend to favor spontaneous, communication-driven invention over stable, organized information.

In the spirit of IndieWeb itself, then, I publish this page on my own website, and hope that others find it useful.

Style note: Singular, capital-W Webmention refers to Webmention at the conceptual level, particularly its role as a web technology standard. Lowercase-w webmentions, singular or plural, describe the individual messages adhering to the Webmention protocol. So: “I can send you a webmention, because your website supports Webmention.” (This distinction follows the guidelines of IndieWeb’s style guide.)

Introduction

What is Webmention?

Webmention, as codifed by the W3C, is the connective tissue of an open, federated communication network of independent websites.

When I wish to inform a certain website – whether mine, or someone else’s – that another website has linked to it in some interesting fashion, I can send it a webmention. I can do that manually, or through a software tool, or I can set up my own content-management software to automatically do it for me every time I post or update an article on my own site.

Whichever way I send it, if the target website supports the Webmention protocol, then it will receive, process, and react to the webmention in some way appropriate to the context of the source-link. For example, if the link seems to be a public reply in direct response to the page linked to, then the target page way wish to republish it onto itself as a comment, with a link back to the original. Or, perhaps, the link is marked up as a social-media-style “like”, in which case the target page might simply increment its little thumbs-up counter of public praise.

By letting you participate in conversations across the internet while publishing primarily to your own website, Webmention gives you an open alternative to relying on closed, corporate-owned platforms such as Twitter or Medium, without giving up on the interactions with readers that those sites so famously provide. You can always “syndicate” your content to these platforms, as well, to increase your reach – but your content’s canonical home stays on your own domain.

Webmention has use-cases beyond public writing and reacting, as well; for example, you can post an announcement of a public event you intend to host, and then receive webmentions that act as RSVPs, publishing them as you receive them.

How webmentions work

Technologically, a webmention message is very simple, containing only two pieces of data: a source and a target, both of which are URLs that point to web pages on the public internet. (Certainly, one can adapt the technology to work with non-public pages, or use URLs that don’t refer to “web pages” per se – but for simplicity’s sake, I will keep my focus on the common case.)

A program sending a webmention to a certain website will check various places where that website might name an endpoint that acts as a broker for any webmentions targeting it. For example, the target website might put a <link> tag in its HTML that identifies its Webmention handler. (The page you are now reading, in fact, uses this method, as you can see in its source.) If the sender finds such an endpoint, then it delivers the webmention to it via the HTTP POST protocol.

The software running at the endpoint will then check whether that webmention is valid: the content found at its source URL must actually link to the target in some way. If so, then the endpoint will tell the target website about it. (Details about storing webmentions, and communicating with the target, lay entirely with the endpoint; the formal Webmention protocol doesn't prescribe anything here.) Finally, the target of the new, verified webmention can display or otherwise react to it however it wishes: displaying a comment, acknowledging a repost, and so on.

Webmentions and Microformats

Webmentions get really interesting when paired with microformats, little bits of invisible metadata that web authors can embed in their work – again, either manually or with the assistance of software tools. Microformats provide machine-readable hints about intent and context to any programs that “read” that web page.

So, the author of a page can use microformats to tell a machine scanning its source about themselves, incuding their name and an avatar-graphic. They can also declare the page’s context within the larger web, perhaps as a reply to some other page at a certain URL, or a commented pull-quote of its content, or even an RSVP to an event listed there.

Software processing a webmention will check the source page for microformats in order to learn all it can about who wrote it, what they wrote (including the article’s title and summary, if supplied), and why they made this public mention. All this information, taken together, will help the receiving software to decide what to do about this mention: whether to display it as a comment (perhaps with author picture and a tidy summary), or to acknowledge it as a syndication request, or increment an event’s “number of people attending” counter, and so on.

(And, yes, the program must also have the ability to reject the webmention as spam, or as serving some other distasteful purpose – and quietly decline to publish it, with an option to block its source from further consideration.)

Examples

A few places to see Webmention in action right now:

• IndieWeb.xyz and IndieNews both demonstrate Webmention’s ability to act as a syndication medium for news-aggregator sites.

  An author can use microformats to indicate intent to syndicate an article to one of these sites, and then send it a webmention; the other site will respond by publishing the link and article summary.

• Every article on my personal blog, Fogknife, displays the webmentions it has received under the article content, sorting likes, reposts, and replies apart from “generic” mentions. This post, for example, displays a variety of mentions.

• Every event URL on the IndieWeb Events site can receive RSVPs delivered via webmention. In this way, a person could make a short public post about their plans to attend, and the event page would update itself appropriately.

• The IndieWeb Wiki links to plenty more examples from folks’ personal sites.

• And finally, the page you are now reading concludes with its own webmention section.

Resources

Learning about Webmention (and Microformats)

• An excellent, thorough, and illustrated introduction by Chris Aldrich, published on A List Apart.

• An article by me about “passive” and “active” uses of Webmention, published on my personal blog.

• Microformats.io teaches you the basics of Microformats, which can add context and meaning to webmentions.

• IndieWeb’s wiki page about Webmention is a bit wild and unkempt, piled high with years of links – and thus an undeniable first-order resource, for those who wish to dig deeper.

• IndieWebify.Me presents an interactive step-by-step guide to transforming a website whose domain you control into an IndieWeb site, including laying down the basics for Webmention support.

  Running through these exercises will introduce you to quite a few other IndieWeb technologies and principles, as well.

Using Webmention

• Webmention.io is a free service that can act as any website’s Webmention endpoint, and offers an API to query for webmentions that a site has received. You can also use its web interface to view and manage webmentions.

  Due to its ease of setup, many people and projects begin their Webmention experimentation here. It pairs well with projects like webmention.js, which displays Webmention.io-stored data as HTML.

  While I both favor and recommend solutions that minimize reliance on third-party dependencies, Webmention.io nonetheless offers a great place to start playing with this technology.

• Bridgy is a free service that will send webmentions to registered websites based on posts made to Twitter, Instragram, and other social media “silos”.

  For example, you could tweet a link to a self-hosted blog entry, which – via microformats – acknowledges its own syndication to Twitter. If someone retweets that link, then Bridgy will send your website a “repost”-style webmention, which it can then acknowledge or display however it wishes.

• Telegraph is a simple service that lets you send webmentions through a web UI or through an API.

• The IndieWeb Wiki maintains a list of publishing software that supports Webmention.

  Popular entries include the IndieWeb Plugin for Wordpress, which enables a whole raft of IndieWeb technologies including Webmention, and Known as a blogging platform designed entirely with IndieWeb principles in mind.

• Whim is a command-line program by yours truly that can receive, process, store, display, and send webmentions.

• The official Webmention implementation list links to a handful of open-source command-line utilities.

Developing with Webmention

• It all comes down the the W3C Recommendation document for Webmention, of course.

• Webmention Rocks! tests and validates Webmention implementations.

• The IndieWeb Wiki links to Webmention code libraries for a variety of programming languages.

Good luck and have fun

If you found this article useful, you can drop me a line. Or, you know, send this page a webmention.

Thanks to Darius Kazemi for helpful suggestions with early drafts of this page.

The content of this article is licensed under a Creative Commons Attribution 4.0 International License, attributable to Jason McIntosh (https://jmac.org).