Abstract

Webmention is a simple way to notify any URL when you link to it on your site. From the receiver's perspective, it's a way to request notifications when other sites link to it.

Author's Note

This section is non-normative.

This specification was contributed to the W3C from the
IndieWebCamp community. More
history and evolution of Webmention can be found on the
IndieWebCamp wiki.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Publication as a First Public Working Draft does not imply endorsement by the W3C
Membership. This is a draft document and may be updated, replaced or obsoleted by other
documents at any time. It is inappropriate to cite this document as other than work in
progress.

Aaron's server verifies that target in the webmention is a valid permalink on Aaron's blog (if not, processing stops)

Aaron's server verifies that the source (when retrieved, after following redirects [FETCH]) in the webmention contains a hyperlink to the target (if not, processing stops)

2. Webmention Protocol

2.1 Sending Webmentions

2.1.1 Sender discovers receiver webmention endpoint

The sender MUST fetch the target URL and check for an HTTP Link header [RFC5988]
with rel="webmention", or a <link> or
<a> element with rel="webmention". If more than
one of these is present, the first HTTP Link header takes precedence,
followed by the first <link> element, and finally
the first <a> element. Clients MUST support all
three options and fall back in this order.

The endpoint MAY be a relative
URL, in which case the sender MUST resolve it relative to the
target URL according to the [URL] specification.

Senders MAY initially make an HTTP HEAD request [RFC2616] to
check for the Link header before making a GET request.

This specification uses the link rel registry as defined by [HTML5]
for both HTML and HTTP link relations.

2.1.2 Sender notifies receiver

The sender MUST post x-www-form-urlencoded [HTML5] source and
target parameters to the webmention endpoint, where
source is the URL of the sender's page containing a link,
and target is the URL of the page being linked to.

The webmention endpoint will validate and process the request, and
return an HTTP status code [RFC2616]. Most often, 202 Accepted
or 201 Created will be returned, indicating that the
request is queued and being processed asynchronously to prevent
DoS attacks. If the response code is 201, the Location
header will include a URL that can be used to monitor the
status of the request.

2.2 Receiving Webmentions

Upon receipt of a POST request containing the source and
target parameters, the receiver SHOULD queue and process
the request asynchronously to prevent DoS attacks. There are three
possible responses to the request, depending on how the receiver
processes it.

If the receiver creates a status page which the sender can use to
check the status, the receiver MUST reply with an HTTP 201 Created
response with a Location header pointing to the status
URL. The response body MAY contain content, in which case a human
readable response is recommended.

Example 3

HTTP/1.1 201 Created
Location: http://aaronpk.example/webmention/DEhB9Jme
Content-type: text/plain
The webmention is being processed. You can check on its status here: http://aaronpk.example/webmention/DEhB9Jme

If the receiver processes the request asynchronously but does not
return a status URL, the receiver MUST reply with an HTTP 202 Accepted
response. The response body MAY contain content, in which case a
human readable response is recommended.

Example 4

HTTP/1.1 202 Accepted
Content-type: text/plain
The webmention is being processed

If the receiver chooses to process the request and perform the
verification step synchronously (not recommended), it MUST respond
with a 200 OK status on success.

2.2.1 Request Verification

The receiver MUST check that source and target are valid URLs [URL]
and are of schemes that are supported by the receiver. (Most
commonly this means checking that the source and target
schemes are http or https).

The receiver SHOULD check that target is a valid resource that it
can accept webmentions for. This check SHOULD happen
synchronously to reject invalid webmentions before more in-depth
verification begins.

2.2.2 Webmention Verification

Webmention verification SHOULD be handled asynchronously to
prevent DoS attacks.

If the receiver is going to use the webmention in some way,
(displaying it as a comment on a post, incrementing a "like"
counter, notifying the author of a post), then it MUST perform an
HTTP GET request on source, and follow any HTTP redirects
(up to a self-imposed limit such as 20) to confirm that it actually
links to target.

The receiver SHOULD use per-media-type rules to determine whether
the source document links to the target URL. For example, in an
[HTML5] document, the receiver should look for <a href="*">,
<img href="*">, <video src="*">
and other similar links. In a [JSON] document, the receiver should
look for properties whose values are an exact match for the URL.
If the document is plain text, the receiver should look for the URL
by searching for the string. Other content types may be handled at
the implementer's discretion. The source document MUST have an exact
match of the target URL provided in order for it to be considered a
valid link.

At this point, the receiver MAY publish content from this webmention
on the target page or other pages, along with any other data it picks
up from the source. For example, the receiver may display the
contents of the source as a comment on the post.

2.2.3 Error Responses

If the webmention was not successful because of something the
sender did, it MUST return a 400 Bad Request
status code and MAY include a description of the error in the response body.

Possible sender-related errors that can be returned synchronously
before making a GET request to the source:

Specified target URL not found.

Specified target URL does not accept webmentions.

source URL was malformed or is not a supported URL scheme (e.g. a mailto: link)

Possible sender-related errors that can occur after fetching the
contents of the source URL:

source URL not found.

source URL does not contain a link to the target URL.

If the webmention was not successful because of an error on
the receiver's server, it SHOULD return a 500 Internal Server Error
status code and MAY include a description of the error in the response body.

2.2.4 Updating existing webmentions

If receiver had received a webmention in the past with the same
source and target then,

If both the verification steps are successful, it SHOULD update any existing data it picked from source for the existing webmention.

When a webmention implementation does support updating (AKA a "webmention update implementation"), MUST support updating data from properties of the primary object of the source (e.g. properties of the h-entry of the page).

A webmention update implementation MAY support updating data from the h-entry of the page. If an implementation does support this, it MUST support it according to the [microformats2-parsing] and [h-entry] specifications.

A webmention update implementation MAY support updating data from children, or other descendant objects of the primary object (e.g. a comment h-entry inside the h-entry of the page). If an implementation does support this, it MUST support it according to the [Salmention] extension specification (AKA a "Salmention implementation").

A Salmention implementation MAY support updating data from children of the h-entry of the page. If an implementation does support this, it MUST support it according to the [microformats2-parsing] and [h-entry] specifications.

If it received a 410 Gone status code on step 2 (performing a GET request on source), or received a 200 OK status code and does not find a link to target on source, it SHOULD delete the existing webmention.

Processing webmentions SHOULD be idempotent. For example, receiving multiple webmentions for the same source and target with no content changes should not show as multiple replies.

3. Security Considerations

3.1 Preventing Abuse

The verification process SHOULD be queued and processed asynchronously to prevent DoS attacks.

Receivers SHOULD moderate or otherwise verify webmentions before displaying them.

Receivers MAY periodically re-verify webmentions and update them.

If a receiver chooses to publish data it picks up from source, it should ensure that the data is encoded and/or filtered to prevent XSS and CSRF attacks.

3.2 Limits on GET requests

The Webmention protocol relies on the sender making a GET (or HEAD)
request to discover the receiver's endpoint, followed by the receiver
making a GET request to the sender's web page to verify the link.
This means a sender can cause a receiver to make GET requests to
arbitrary URLs, opening up a potential DoS vector.

Receivers SHOULD place limits on the amount of data and time they
spend fetching unverified source URLs. For example, if a source URL
doesn't respond within 5 seconds, it can treat that as a failure.
Similarly, the receiver can fetch only the first 1mb of the page,
since any reasonably HTML or JSON page will be smaller than that.

A. Extensions

This section is non-normative.

The following Webmention Extension Specifications have 2+ interoperable implementations live on the web and are thus listed here:

D.2 Plugins

D.3 Tools

node-webmention-testpinger is a tool to ping your site with a variety of webmentions markup. Contains copies of a couple of real world examples of mentions that it enables you to ping locally to a development copy of your site.

node-webmention-testendpoint is tool to test your webmention client. Generates a demo-post and a demo-endpoint to test if your client parses the webmention-endpoint correctly and to check if the ping body is transmitted correctly.

stapibas is a self-hosted service to send and receive webmentions for websites and blogs. It can be used to send out webmentions and pingbacks for new posts on static sites.

A Firefox Add-On which allows you to send webmentions via a context menu

Checkmention lets you test your webmention implementation on your indieweb site, and whether it robustly detects certain types of XSS attacks. It also allows you to test for authorship spoofing.

jekmentions is a service that works as webmention endpoint and saves the received webmentions in a GitHub repository, so that they can be used and shown in a Jekyll blog.

mention-tech is a service that can receive webmentions on behalf of anyone via both webmention directly, and a web form on its home page.

webmention.herokuapp.com receives webmentions for any registered page and allows them to be embedded through javascript.

webmention.io is an open-source project and hosted service for receiving webmentions and pingbacks on behalf of your indieweb site.

E. Acknowledgements

The editor wishes to thank Sandeep Shetty
for contributing the original draft of the webmention specification.

Additionally, the editor wishes to thank the IndieWebCamp
community and other implementers for their support, encouragement and enthusiasm,
including but not limited to: Amy Guy, Benjamin Roberts, Ben Werdmüller, Dave Wilkinson, Rob Sanderson, and Tantek Çelik.