Webmention

Webmention
Webmention
W3C
Recommendation
12 January 2017
This version:
Latest published version:
Latest editor's draft:
Test suite:
Implementation report:
Previous version:
Editor:
Aaron Parecki
Repository:
Github
Issues
Commits
Please check the
errata
for any errors or issues reported since publication.
The English version of this specification is the only normative version. Non-normative
translations
may also be available.
W3C
MIT
ERCIM
Keio
Beihang
).
W3C
liability
trademark
and
permissive document license
rules apply.
Abstract
Webmention is a simple way to notify any URL when you mention it on your site. From the receiver's perspective, it's a way to request notifications when other sites mention it.
Author's Note
This section is non-normative.
This specification was contributed to the
W3C
from the
IndieWeb
community. More history and evolution of Webmention can be found on the
IndieWeb 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 https://www.w3.org/TR/.
This document was published by the
Social Web Working Group
as a Recommendation. If you wish to make comments regarding this document, please send them to
public-socialweb@w3.org
archives
). All comments are welcome.
Please see the Working Group's
implementation
report
This document has been reviewed by
W3C
Members, by software developers, and by other
W3C
groups and interested parties, and is endorsed by the Director as a
W3C
Recommendation. It is a stable document and may be used as reference material or cited from another document.
W3C
's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
This document was produced by a group operating under the
5 February 2004
W3C
Patent
Policy
W3C
maintains a
public list of any patent
disclosures
made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains
Essential
Claim(s)
must disclose the information in accordance with
section
6 of the
W3C
Patent Policy
W3C
expects the functionality specified in this Recommendation will not be affected by changes to Fetch.
This document is governed by the
1 September 2015
W3C
Process Document
1.
Introduction
A Webmention is a notification that one URL links to another. For example, Alice writes an interesting post on her blog. Bob then writes a response to her post on his own site, linking back to Alice's original post. Bob's publishing software sends a Webmention to Alice notifying that her article was replied to, and Alice's software can show that reply as a comment on the original post.
Sending a Webmention is not limited to blog posts, and can be used for additional kinds of content and responses as well. For example, a response can be an RSVP to an event, an indication that someone "likes" another post, a "bookmark" of another post, and many others. Webmention enables these interactions to happen across different websites, enabling a distributed social web.
1.1
Social Web Working Group
This section is non-normative.
Webmention
is one of several related specifications being produced by the Social Web Working Group. Implementers interested in alternative approaches and complimentary protocols should start by reading the overview document [
social-web-protocols
].
1.2
Background
This section is non-normative.
The Webmention spec began as a simplified version of the [
Pingback
] spec. Where Pingback required sending the source and target URLs in an XML-RPC payload, Webmention simplified that to a form-encoded payload, which meant it could easily be used in HTML forms, was easier to work with since more tools exist for form-encoded payloads, and was not vulnerable to accidentally exposing other parts of a system's code via XML-RPC.
Webmention then continued on to more thoroughly specify the details of sending and verifying the request, and expanded to support sending notifications when a source document was updated or deleted. More information can be found in the
Webmention FAQ
on the IndieWeb wiki.
1.3
Overview
This section is non-normative.
A typical Webmention flow is as follows:
Alice posts some interesting content on her site (which is set up to receive Webmentions).
Bob sees this content and comments about it on his site, linking back to Alice's original post.
Using Webmention, Bob's publishing software automatically notifies Alice's server that her post has been linked to by the URL of Bob's post.
Alice's publishing software verifies that Bob's post actually contains a mention of her post and then includes this information on her site.
1.4
Protocol Summary
This section is non-normative.
Webmentions are sent "from" a source URL "to" a target URL to notify the target that it has been mentioned at the source URL.
User Aaron writes a post on his blog.
User Barnaby writes a post on his blog that links to Aaron's post.
After publishing the post (i.e., after it has a URL), Barnaby's server notices the mention of Aaron's post as part of the publishing process.
Barnaby's server does Webmention discovery on Aaron's post to find its Webmention endpoint (if not found, process stops).
Barnaby's server sends a Webmention notification to Aaron's post's Webmention endpoint with:
source
set to Barnaby's post's permalink
target
set to Aaron's post's permalink.
Aaron's server receives the Webmention.
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
in the Webmention (when retrieved, after following redirects [
FETCH
]) contains a hyperlink to the
target
(if not, processing stops).
2.
Conformance
The key words "
MUST
", "
MUST NOT
", "
REQUIRED
", "
SHALL
", "
SHALL NOT
", "
SHOULD
", "
SHOULD NOT
", "
RECOMMENDED
", "
MAY
", and "
OPTIONAL
" in this document are to be interpreted as described in [
RFC2119
].
2.1
Conformance Classes
Webmention implementations are either senders or receivers. This section describes the conformance criteria for both.
Listed below are known types of Webmention implementations.
Senders
A Webmention Sender is an implementation that sends Webmentions. In order for a Sender to send a Webmention, there must first be a document at a URL that is accessible to the Receiver.
The conformance criteria for Webmention senders is described in
Sending Webmentions
Listed below are some known types of Webmention Senders.
Blogging or microblogging software
Plugins for existing CMS software
Browser plugins to send a Webmention from a context menu on behalf of the page you're viewing
Web APIs to offload the Webmention endpoint discovery and Webmention delivery
Proxy services that converts existing social media posts to HTML posts and sends Webmentions
Receivers
A Webmention Receiver is an implementation that receives Webmentions to one or more target URLs on which the Receiver's Webmention endpoint is advertised. In order to receive a Webmention, there must be a URL that advertises the Receiver's Webmention endpoint. The URL is not considered part of the Receiver's implementation, as it may exist in an entirely different system or domain.
The conformance criteria for Webmention receivers is described in
Receiving Webmentions
Listed below are some known types of Webmention Receivers.
Blogging or microblogging software
Plugins for existing CMS software
Web services and APIs to receive Webmentions and display them as comments via Javascript embed
2.2
Test Suite and Reporting
Please submit your implementation reports at
. Instructions are provided at the URL. The implementation report template references the tests available at
webmention.rocks
webmention.rocks
provides many test cases you can use to live-test your implementation. It also is a useful tool to use while developing a Webmention implementation, as it provides detailed responses when errors are encountered.
3.
Webmention Protocol
This specification uses the link rel registry as defined by [
HTML5
] for both HTML and HTTP link relations.
3.1
Sending Webmentions
3.1.1
Create a source document that mentions the target
Webmentions are sent "from" a source URL "to" a target URL to notify the target that it has been mentioned at the source URL. Before a Webmention can be sent, there needs to be a source URL to send the Webmention "from", often a blog post but may be any type of content.
For example, the URL at https://waterpigs.example/post-by-barnaby may contain the following HTML that has a link to Aaron's post.
Example 1

html
body
href
"https://aaronpk.example/post-by-aaron"
This is a great post
body
html
3.1.2
Sender discovers receiver Webmention endpoint
The sender
MUST
fetch the target URL (and follow redirects [
FETCH
]) and check for an HTTP Link header [
RFC5988
] with a rel value of
webmention
. If the content type of the document is HTML, then the sender
MUST
look for an HTML

and

element with a rel value of
webmention
. If more than one of these is present, the first HTTP Link header takes precedence, followed by the first

or

element in document order. Senders
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 [
URL
].
The endpoint
MAY
contain query string parameters, which
MUST
be preserved as query string parameters and
MUST NOT
be sent as POST body parameters when sending the Webmention request.
Senders
MAY
initially make an HTTP HEAD request [
RFC7231
] to check for the Link header before making a GET request.
Example 2
GET
/post-by-aaron
HTTP/1.1
Host
: aaronpk.example
HTTP/1.1
200
OK
Link
: ; rel="webmention"

head
...
link
href
"http://aaronpk.example/webmention-endpoint"
rel
"webmention"
/>
...
head
body
....
href
"http://aaronpk.example/webmention-endpoint"
rel
"webmention"
webmention
...
body
html
Senders
MAY
customize the HTTP User Agent [
RFC7231
] used when fetching the target URL in order to indicate to the recipient that this request is made as part of Webmention discovery. In this case, it is recommended to include the string "Webmention" in the User Agent. This provides people with a pointer to find out why the discovery request was made.
3.1.3
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.
Note that if the Webmention endpoint URL contains query string parameters, the query string parameters
MUST
be preserved, and
MUST NOT
be sent in the POST body.
The Webmention endpoint will validate and process the request, and return an HTTP status code [
RFC7231
]. Most often,
202 Accepted
or
201 Created
will be returned, indicating that the request is queued and being processed asynchronously to prevent DoS (Denial of Service) 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.
Any
2xx
response code
MUST
be considered a success.
Example 3
POST
/webmention-endpoint
HTTP/1.1
Host
: aaronpk.example
Content-Type
: application/x-www-form-urlencoded
source=https:
//waterpigs.example/post-by-barnaby&
target=https:
//aaronpk.example/post-by-aaron
HTTP/
1.1
202
Accepted
3.1.4
Sending Webmentions for updated posts
If the source URL was updated, the sender
SHOULD
re-send any previously sent Webmentions, (including re-sending a Webmention to a URL that may have been removed from the document), and
SHOULD
send Webmentions for any new links that appear at the URL.
This allows the recipients of Webmentions to update their display of the source document, or otherwise notify the recipient that a post that mentioned one of their URLs was updated.
When sending a Webmention when a post is updated, the sender
MUST
re-discover the Webmention endpoint of each target URL, in case the target has updated their Webmention endpoint.
If a response to the source URL is shown on the source URL page (e.g. as a comment), then sender
SHOULD
treat that as an update of the source URL and re-send any previously sent Webmentions.
3.1.5
Sending Webmentions for deleted posts
If the source URL was deleted, the sender
SHOULD
return an HTTP
410 Gone
status code for the URL, and
SHOULD
display a "tombstone" representation of the deleted post, typically by blanking out the values of any properties in the post, and/or replacing the primary content of the post (e.g. the name and/or content of [
h-entry
]) with "Deleted". The sender
SHOULD
then re-send Webmentions for every previously sent Webmention for that document.
This allows receivers which may have displayed a previously received Webmention as a comment or other interaction to remove it from view if they support deletes, while providing a reasonable fallback for receivers which only support updates.
3.2
Receiving Webmentions
Upon receipt of a POST request containing the
source
and
target
parameters, the receiver
SHOULD
verify the parameters (see
Request Verification
below) and then
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.
Example 4
HTTP/1.1
201
Created
Location
: 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 5
HTTP/1.1
202
Accepted
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.
3.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
MUST
reject the request if the source URL is the same as the target URL.
The receiver
SHOULD
check that
target
is a valid resource for which it can accept Webmentions. This check
SHOULD
happen synchronously to reject invalid Webmentions before more in-depth verification begins. What a "valid resource" means is up to the receiver. For example, some receivers may accept Webmentions for multiple domains, others may accept Webmentions for only the same domain the endpoint is on.
Note that a target URL may contain a fragment identifier, and if the receiver limits which URLs can receive Webmentions, the fragment
SHOULD
be ignored when checking if the URL is supported.
3.2.2
Webmention Verification
Webmention verification
SHOULD
be handled asynchronously to prevent DoS (Denial of Service) 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, following any HTTP redirects (and
SHOULD
limit the number of redirects it follows) to confirm that it actually mentions the target. The receiver
SHOULD
include an HTTP Accept header indicating its preference of content types that are acceptable.
The receiver
SHOULD
use per-media-type rules to determine whether the source document mentions the target URL. For example, in an [
HTML5
] document, the receiver should look for