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/.

This document was published by the Social Web Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-socialweb@w3.org (subscribe, archives). W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 21 June 2016. All comments are welcome.

Please see the Working Group's implementation report.

Publication as a Candidate Recommendation 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.

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.

This document is governed by the 1 September 2015 W3C Process Document.

1. Introduction

At a basic level, a Webmention is a notification that one URL links to another.

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].

1.1 Overview

This section is non-normative.

A typical Webmention flow is as follows:

  1. Alice posts some interesting content on her site (which is set up to receive Webmentions).
  2. Bob sees this content and comments about it on his site, linking back to Alice's original post.
  3. 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.
  4. Alice's publishing software verifies that Bob's post actually contains a link to her post and then includes this information on her site.

1.2 Protocol Summary

This section is non-normative.

  1. User Aaron writes a post on his blog.
  2. User Barnaby writes a post on his blog that links to Aaron's post.
  3. After publishing the post (i.e., after it has a URL), Barnaby's server notices the link to Aaron's post as part of the publishing process.
  4. Barnaby's server does Webmention discovery on Aaron's post to find its Webmention endpoint (if not found, process stops).
  5. 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.
  6. Aaron's server receives the Webmention.
  7. Aaron's server verifies that target in the Webmention is a valid permalink on Aaron's blog (if not, processing stops).
  8. 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

The conformance criteria for Webmention senders is described in Sending Webmentions

Receivers

The conformance criteria for Webmention receivers is described in Receiving Webmentions

2.2 Candidate Recommendation Exit Criteria

For this specification to exit the CR stage, there must be at least two independent, interoperable implementations of each feature. Each feature may be implemented by a different set of products. There is no requirement that all features be implemented by a single product. For the purposes of this criterion, we define the following terms:

2.2.1 Sender

A Webmention Sender is an implementation that sends Webmentions, the conformance criteria are described in Sending Webmentions. In order to send a Webmention, the Sender first creates a document at a URL that is accessible to the Receiver.

2.2.2 Receiver

A Webmention Receiver is an implementation that receives Webmentions to one or more target URLs on which the Receiver's Webmention endpoint is advertised. The conformance criteria for Receivers are described in Receiving Webmentions. 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.

2.2.3 Independent

Each implementation must be developed by a different party and cannot share, reuse, or derive from code used by another qualifying implementation. Sections of code that have no bearing on the implementation of this specification are exempt from this requirement.

2.2.4 Interoperable

A Sender and Receiver implementation are considered interoperable for a specific feature when the Sender 1) can discover the Webmention endpoint for the target URL for all specified ways of finding the endpoint (allowing the Receiver to change the way the endpoint is advertised without changing the Sender implementation), and 2) considers the Webmention request successful for all specified ways a Receiver may indicate success.

2.2.5 Implementation

An Implementation is a Webmention Sender or Receiver which meets all of the following criteria:

  • implements the corresponding conformance class of the specification
  • is available to the general public, as downloadable software or as a hosted service
  • is not experimental (i.e. is intended for a wide audience and could be used on a daily basis)
  • is suitable for a person to use as his/her primary implementation on a website

2.2.6 Feature

For the purposes of evaluating exit criteria, each of the following is considered a feature:

  • Sending a Webmention to a given target URL
  • Re-sending Webmentions and sending new Webmentions when the source document is updated
  • Re-sending Webmentions when the source document is deleted
  • Receiving a Webmention request, processing it synchronously, and responding with HTTP 200
  • Receiving a Webmention request, processing it asynchronously, creating a status URL and responding with HTTP 201
  • Receiving a Webmention request, processing it asynchronously, and responding with HTTP 202 and no other feedback
  • Updates: Receiving a Webmention from a source URL that was previously seen and updating the data it picked up from the source URL
  • Delete: Receiving a Webmention from a source URL which now responds with HTTP 410

2.3 Test Suite and Reporting

Please submit your implementation reports at http://webmention.net/implementation-reports/. 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 good 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 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, or an HTML <link> or <a> 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 <link> or <a> element in document order. 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 [RFC3986].

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 [RFC2616] to check for the Link header before making a GET request.

Example 1
GET /post-by-aaron HTTP/1.1
Host: aaronpk.example
HTTP/1.1 200 OK
Link: <http://aaronpk.example/webmention-endpoint>; rel="webmention"

<html>
<head>
...
<link href="http://aaronpk.example/webmention-endpoint" rel="webmention" />
...
</head>
<body>
....
<a href="http://aaronpk.example/webmention-endpoint" rel="webmention">webmention</a>
...
</body>
</html>

3.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.

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 [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.

Any 2xx response code MUST be considered a success.

Example 2
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.3 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.4 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, 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.

3.2.1 Request Verification

The receiver MUST check that source and target are valid URLs [RFC3986] 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.

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 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) and confirm that it actually links to the 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 Webmention.

At this point, the receiver MAY publish content from the source page 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, or may display the author's profile photo in a list of others who have sent similar Webmentions, e.g. showing a list of people who have all "liked" a post.

3.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.

3.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 (i.e., a "Webmention update implementation"), it 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 children, or other descendant objects of the primary object (e.g. a comment h-entry inside the h-entry of the page). Note: Implementations that support this may wish to consider supporting it according to the [Salmention] extension.
  • 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, or mark it as deleted.
  • Processing Webmentions SHOULD be idempotent. That is, receiving multiple Webmentions for the same source and target with no content changes should not show as multiple replies.

4. Security Considerations

4.1 Preventing Abuse

4.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 reasonable HTML or JSON page will be smaller than that.

4.3 Avoid sending Webmentions to localhost

When the sender discovers the receiver's Webmention endpoint, there is no legitimate reason for the endpoint to be localhost or any other loopback address. If the sender has any services that listen on localhost that don't require authentication, it's possible for a malicious Webmention receiver to craft a Webmention endpoint that could cause the sender to make an arbitrary POST request to itself.

During the discovery step, if the sender discovers the endpoint is localhost or a loopback IP address (127.0.0.0/8), it SHOULD NOT send the Webmention.

4.4 Cross-Site Request Forgery

This specification does not define any special handling of a Webmention request that may contain additional headers or parameters such as authentication headers or session cookies. However, if a Webmention endpoint does accept requests with additional headers, it SHOULD protect itself against Cross-Site Request Forgery (CSRF) attacks. One way to prevent CSRF attacks is by including a CSRF token in a query string parameter of the Webmention endpoint, so that a Webmention sender finds the token when discovering the endpoint.

For example, the target URL could advertise a Webmention endpoint that includes a CSRF token:

Example 5
GET /post-by-aaron HTTP/1.1
Host: aaronpk.example
HTTP/1.1 200 OK
Link: <http://aaronpk.example/webmention?csrf=Q0NTVhYjI0NTVkNDA3M>; rel="webmention"

Then, when the Webmention endpoint is processing a request, it can first check the validity of the CSRF token before any other processing.

4.5 Limit access to protected resources

It is possible for an attacker to advertise a Webmention endpoint that points to an arbitrary URL. As such, if you install software that sends Webmentions on a server that is behind a firewall or otherwise has access to normally protected resources, you should be aware that an attacker can cause the server to send a POST request to an internal server. You SHOULD take precautions to ensure this server cannot access protected resources by either:

5. IANA Considerations

The link relation type below has been registered by IANA per Section 6.2.1 of [RFC5988]:

Relation Name:
webmention
Description:
Identifies a target URI that supports the Webmention protocol. This allows clients that mention a resource in some form of publishing process to contact that endpoint and inform it that this resource has been mentioned.
Reference:
W3C Webmention Specification (http://www.w3.org/TR/webmention/)
Notes:
This is a similar "Linkback" mechanism to the ones of Refback, Trackback, and Pingback. It uses a different protocol, though, and thus should be discoverable through its own link relation type.

A. URIs for Form-Encoded Properties

If your implementation wants to treat the source and target parameters as URIs, you can prefix the terms with http://www.w3.org/ns/webmention#.

B. Extensions

This section is non-normative.

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

B.1 Vouch

The [Vouch] protocol is an anti-spam extension to Webmention.

B.2 Salmention

The [Salmention] protocol is an extension to Webmention to propagate comments and other interactions upstream.

C. Resources

This section is non-normative.

C.1 Articles

This section is non-normative.

You can find a list of articles about Webmention on the IndieWebCamp wiki.

C.2 Implementations

This section is non-normative.

You can find a list of Webmention implementations on webmention.net

D. 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.

E. Change Log

This section is non-normative.

E.1 Changes from 29 April 2016 WD to this version

E.2 Changes from 20 April 2016 WD to 29 April 2016 WD

E.3 Changes from 29 March 2016 WD to 20 April 2016 WD

E.4 Changes from 1 March 2016 WD to 29 March 2016 WD

E.5 Changes from 12 January 2016 FPWD to 1 March 2016 WD

This section lists changes from the 12 January 2016 FPWD to this Working Draft

F. References

F.1 Normative references

[FETCH]
Anne van Kesteren. WHATWG. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML5]
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. W3C. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
[RFC2119]
S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC2616]
R. Fielding; J. Gettys; J. Mogul; H. Frystyk; L. Masinter; P. Leach; T. Berners-Lee. IETF. Hypertext Transfer Protocol -- HTTP/1.1. June 1999. Draft Standard. URL: https://tools.ietf.org/html/rfc2616
[RFC3986]
T. Berners-Lee; R. Fielding; L. Masinter. IETF. Uniform Resource Identifier (URI): Generic Syntax. January 2005. Internet Standard. URL: https://tools.ietf.org/html/rfc3986
[RFC5988]
M. Nottingham. IETF. Web Linking. October 2010. Proposed Standard. URL: https://tools.ietf.org/html/rfc5988

F.2 Informative references

[JSON]
D. Crockford. IETF. The application/json Media Type for JavaScript Object Notation (JSON). July 2006. Informational. URL: https://tools.ietf.org/html/rfc4627
[Salmention]
Ben Roberts; Tantek Çelik. IndieWebCamp. Salmention. Living Specification. URL: http://indiewebcamp.com/Salmention
[Vouch]
Aaron Parecki; Tantek Çelik. IndieWebCamp. Vouch. Living Specification. URL: http://indiewebcamp.com/Vouch
[h-entry]
Tantek Çelik. microformats.org. h-entry. Living Specification. URL: http://microformats.org/wiki/h-entry