Skip to main content

Webmention: an introduction for developers

5 min read

Webmention is a simple protocol that allows one website to notify another that it has "mentioned" it - in other words, referenced it in a link. Together with HTML5 microformats, it is one of the building blocks of the indie web. It is also one of the technologies that makes decentralized discussion, event RSVPs and commenting work in Known.

It is not the first protocol to attempt to handle these notifications: previously, trackbacks and pingbacks performed a similar task. Webmention supersedes these technologies by using encoded form content in an HTTP POST request, rather than comparatively more complex XML-RPC calls.

Fundamentals

One site "mentions" another by finding its webmention endpoint, and sending a very simple HTTP POST request that contains the URL of the source website, as well as the target: in other words, the website being linked to.

Let's break that down:

Webmention endpoint discovery

Websites can list their webmention endpoints in a number of ways:

  1. An HTTP Link: header, which looks something like: Link: http://alice.host/webmention-endpoint>; rel="webmention"
  2. A link tag in the header of the page HTML:
  3. An anchor tag in the body of the page HTML:

Note that in each case, a tag has a "rel" relation attribute with the value "webmention". This tells an HTML parser that the link in the tag is a webmention endpoint.

If you're sending webmentions, you need to look for all of these places. Some webmention clients also check for a "rel" value of http://webmention.org/, which was used in an older version of the protocol specification.

Sending the webmention

A webmention is just a form-encoded HTTP POST request. In other words, it's exactly the same kind of request as is sent when you submit most forms on the web.

In fact, you could easily add a form to your website that sends a webmention to your own webmention endpoint. All you'd need is a URL input called source and a URL input called target.

A sample request looks like:

POST /webmention-endpoint HTTP/1.1
Host: alice.host
Content-Type: application/x-www-url-form-encoded

source=http://bob.host/post-by-bob&target=http://alice.host/post-by-alice

Validating a webmention

The receiver of a webmention should check the source URL to make sure that it exists, and make sure that it genuinely links to the target URL.

Further parsing and verification may take place, which we'll discuss below. Once the webmention has been validated, a 202 response is returned in response to the original request:

HTTP/1.1 202 Accepted

http://alice.host/link/to/page/on/target/containing/webmention/

If the webmention couldn't be validated because the source was incorrect or the webmention was malformed, the endpoint should return an HTTP 400 error. If the webmention couldn't be validated because of something that happened on the target site, the endpoint should return an HTTP 500 error.

Ideally, webmentions should be processed asynchronously, to prevent certain kinds of abuse. However, this makes it harder to return the URL of a webmention to the source site.

What can I use this for?

The indie web community has used webmentions as the backbone for decentralized social interactions.

The fundamentals of each kind of interaction is the same. In addition to the webmention protocol standards listed above, each post should be marked up using microformats. These provide further semantic context to the content on a web page by establishing conventions around the way HTML classes are used on page elements. This microformatted markup allows content to be marked up as social actions like comments, replies, RSVPs, likes or reshares. A page can then send a webmention to tell the target about the social action.

Because any page on the web can reply to, RSVP to, like or reshare any other page on the web, the combination of webmention and microformats establishes the backbone to a very simple social web of activities.

Base social interaction standards

Content should be marked up with the h-entry microformat, which identifies it as a post. Ideally it should also be marked up with nested content identifying the author using the h-card microformat.

Using a microformat parser like php-mf2, this markup can be transformed into structured data that a webmention endpoint can use to process interactions.

Many platforms, including Known, store the user photos, names and profiles that are parsed from each post's accompanying h-card, in order to display content in a manner that closely resembles centralized social networks.

Here are some specializations of webmention-enabled social interactions:

Comments

Links to the target page (the page being replied to) should be marked up with a "rel" value of in-reply-to, as well as a microformat class of u-in-reply-to. For example:

link text

RSVPs

An RSVP is a comment in reply to a post about an event, that includes a data tag with the class p-rsvp, where the value is whether you're attending the event (typically "yes", "no" or "maybe"). For example:

Likes

A like is similar to a comment, except that the link contains a class of "u-like-of", and no "rel" value.

Reposts

A repost (or reshare; Twitter calls these a retweet) is the same as a like, but the class on the link is swapped out for "u-repost-of".

Who uses webmentions?

Thousands of Known sites are webmention-compatible, and a growing number of projects use webmention (notably brid.gy, which converts your social interactions on closed networks like Twitter and Facebook into webmentions). It's an easy protocol to build against, and a crucial building block towards building a diverse, decentralized social web.