├── IMPLEMENTATIONS.md └── README.md /IMPLEMENTATIONS.md: -------------------------------------------------------------------------------- 1 | ## Libraries 2 | 3 | * PHP 4 | * [Webmention Client (PHP)](https://github.com/aaronpk/mention-client) 5 | * [phpish/webmention](https://github.com/phpish/webmention) - Simple webmention client (non-OO) in PHP packaged as a composer package. 6 | * [phpish/link_header](https://github.com/phpish/link_header) - Link header (RFC 5988) parser in PHP for webmention endpoint discovery 7 | * Ruby 8 | * [Webmention Client (Ruby)](https://github.com/indieweb/mention-client-ruby) 9 | * Python 10 | * [Webmention Library (Python)](https://github.com/bear/ronkyuu) 11 | 12 | ## Plugins 13 | * [WordPress Plugin](https://github.com/pfefferle/wordpress-webmention) 14 | 15 | ## Projects 16 | 17 | * [Converspace](https://github.com/converspace/converspace) - powers [sandeep.io](http://sandeep.io) 18 | * [idno](https://github.com/idno/idno) 19 | * [Storytlr](http://storytlr.org) - code on [GithHub](https://github.com/storytlr/storytlr) 20 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Webmention 0.2 (RC1) 2 | 3 | Webmention is a simple way to automatically notify any URL when you link to it on your site. From the receivers perpective, it's a way to request notification when other sites link to it. 4 | 5 | It’s a modern alternative to [Pingback](http://www.hixie.ch/specs/pingback/pingback) and other forms of [Linkback](http://en.wikipedia.org/wiki/Linkback). 6 | 7 | Note that the latest, most up-to-date specification is located [on the IndieWebCamp wiki](http://indiewebcamp.com/webmention). 8 | 9 | ### Versions 10 | 11 | #### Latest Version: 12 | http://indiewebcamp.com/webmention 13 | 14 | #### Previous Versions: 15 | * [version 0.1](https://github.com/converspace/webmention/blob/c9ab07947d00656237d9a5e626c78148da7166eb/README.md) 16 | 17 | 18 | ### Editors 19 | * [Sandeep Shetty](http://sandeep.io/) (sandeep.shetty@gmail.com) 20 | 21 | ### Contributors 22 | * [Aaron Parecki](http://aaronparecki.com/) (aaron@parecki.com) 23 | * [Barnaby Walters](http://waterpigs.co.uk/) 24 | 25 | 26 | ### License 27 | 28 | [CC0](http://creativecommons.org/choose/zero/)+[OWFa](http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0) 29 | 30 | CC0 To the extent possible under law, the editors and contributors have waived all copyright and related or neighboring rights to this work. In addition, as of 27 September 2013, the editors and contributors have made this specification available under the Open Web Foundation Agreement Version 1.0. 31 | 32 | ## Introduction 33 | 34 | Here's a typical webmention flow: 35 | 36 | 1. Alice posts some interesting content on her site (which is setup to receive webmentions). 37 | 2. Bob sees this content and comments about it on his site, linking back to Alice's original post. 38 | 3. Using webmention, Bob's publishing software automatically notifies Alice's server that her post has been linked to along with the URL to Bob's post. 39 | 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. 40 | 41 | 42 | ## Protocol Flow 43 | 44 | ### Sender discovers Receiver Endpoint 45 | 46 | ```http 47 | GET /post-by-alice HTTP/1.1 48 | Host: alice.host 49 | ``` 50 | ```http 51 | HTTP/1.1 200 OK 52 | Link: ; rel="webmention" 53 | 54 | 55 | 56 | ... 57 | 58 | ... 59 | 60 | 61 | .... 62 | 63 | ... 64 | 65 | 66 | ``` 67 | 68 | The webmention endpoint is advertised in the HTTP Link header or a `` or `` element with `rel="webmention"`. If more than one of these is present, the HTTP Link header takes precedence, followed by the `` element, and finally the `` element. Clients MUST support all three options and fall back in this order. 69 | 70 | ### Sender Notifies Receiver 71 | 72 | ```http 73 | POST /webmention-endpoint HTTP/1.1 74 | Host: alice.host 75 | Content-Type: application/x-www-url-form-encoded 76 | 77 | source=http://bob.host/post-by-bob& 78 | target=http://alice.host/post-by-alice 79 | ``` 80 | ```http 81 | HTTP/1.1 202 Accepted 82 | 83 | http://alice.host/webmentions/222 84 | ``` 85 | 86 | `202 Accepted` is the recommended status code to return indicating that the request SHOULD be queued and processed asynchronously to prevent __DoS attacks__. The response body SHOULD include a URL that can be used to monitor the status of the request. 87 | 88 | If you choose to process the request and perform the [verification](#verification) step synchronously, you can respond with a `200 OK` status on success. 89 | 90 | See [Error Responses](#error-responses) for what to do when the webmention is not successful. 91 | 92 | 93 | 94 | ### Verification 95 | 1. The receiver SHOULD check that `target` is a valid resource belonging to it and that it accepts webmentions. 96 | 2. The receiver SHOULD perform a HTTP `GET` request on `source` to confirm that it actually links to `target` (note that the receiver will need to check the `Content-Type` of the entity returned by `source` to make sure it is a textual response). 97 | 98 | At this point the receiver can choose to publish information about this webmention along with any other data it picks up from `source`. 99 | 100 | 101 | #### Error Responses 102 | 103 | ##### Sender Error 104 | 105 | If the webmention was not successful because of something the sender did, you SHOULD return a `400 Bad Request` status code and MAY include a description of the error in the response body. 106 | 107 | Possible sender related errors (from the [Pingback](http://www.hixie.ch/specs/pingback/pingback) specification): 108 | * Source URL not found. 109 | * Specified target URL not found. 110 | * Source URL does not contain a link to the target URL. 111 | * Specified target URL does not accept webmentions. 112 | 113 | ##### Receiver Error 114 | 115 | If the webmention was not successful because of an error on the receivers server, it SHOULD return a `500 Internal Server Error` status code and MAY include a description of the error in the response body. 116 | 117 | 118 | #### Updating existing webmentions 119 | If receiver had received a webmention in the past with the same `source` and `target` then, 120 | * If both the [verification](#verification) steps are successful, it SHOULD update any existing data it picked from `source` for the existing webmention. 121 | * If it received a 410 on step 2 (performing a `GET` request on `source`) or does not find a link to `target` on `source`, it SHOULD delete the existing webmention. 122 | 123 | 124 | ## Preventing Abuse 125 | * The verification process SHOULD be queued and processed asynchronously to prevent DDoS attacks. 126 | * Receivers SHOULD moderate Webmentions, and if a link is displayed back to the source, SHOULD link to `source` with `rel="nofollow"` to prevent spam. 127 | * Receivers MAY periodically re-verify webmentions and [update them](#updating-existing-webmentions). 128 | * 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. 129 | 130 | 131 | # Implementations 132 | See [IMPLEMENTATIONS](IMPLEMENTATIONS.md) 133 | 134 | # TODO 135 | * Prevention of DDoS 136 | * Malicious attacker could send webmentions to a lot of sites with Alice's site as `source` which will result in a DDoS on Alice's site. 137 | * See [this discussion about Refback](http://krijnhoetmer.nl/irc-logs/whatwg/20111122#l-387). tl;dr: Hixie says "it's already pretty trivial to cause a server to get a lot of GETs, that's not a particularly interesting security issue imho". 138 | * backcompat with v0.1 by also supporting rel="http://webmention.org"? 139 | 140 | 141 | ## See also 142 | 143 | * [Pingback](http://www.hixie.ch/specs/pingback/pingback) 144 | * [Trackback](http://archive.cweiske.de/trackback/trackback-1.2.html) 145 | * [RESTful Pingback](http://www.w3.org/wiki/Pingback) 146 | * [Semantic Pingback](http://aksw.org/projects/semanticpingback) 147 | * [TalkBack](http://elie.im/publication/reclaiming-the-blogosphere-talkBack-a-secure-linkBack-protocol-for-weblogs#.UIWq_k4geoM) 148 | 149 | 150 | ## Let's collaborate 151 | Feel free to [file an issue](https://github.com/converspace/webmention/issues) if you have feedback/questions/suggestions. 152 | 153 | --------------------------------------------------------------------------------