GitHub - dissolve/webmention: A modern alternative to Pingback. (original) (raw)
Webmention 0.2-b1
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.
It’s a modern alternative to Pingback and other forms of Linkback.
Versions
Latest Version:
Previous Versions:
Editors
Contributors
License
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.
Introduction
Here's a typical webmention flow:
- Alice posts some interesting content on her site (which is setup 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 along with the URL to Bob's post.
- Alice's publishing software verifies that Bob's post actually contains a link to her post and then includes this information on her site.
Protocol Flow
Sender discovers Receiver Endpoint
GET /post-by-alice HTTP/1.1 Host: alice.host
HTTP/1.1 200 OK Link: http://alice.host/webmention-endpoint; rel="webmention"
... ...Sender Notifies Receiver
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& callback=http://bob.host/callback/321
The callback parameter MAY be omitted if you choose to poll a returned link for asynchronous updates. See Asynchronous Callback for the callback protocol flow.
HTTP/1.1 202 Accepted Link: http://alice.host/webmentions/222; rel="status"
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. See Asynchronous Status for queue responses.
If you choose to process the request and perform the verification step synchronously, you can respond with a 200 OK status on success.
See Error Responses for what to do when the webmention is not successful.
Verification
- The receiver SHOULD check that
targetis a valid resource belonging to it and that it accepts webmentions. - The receiver SHOULD perform a HTTP
GETrequest onsourceto confirm that it actually links totarget(note that the receiver will need to check theContent-Typeof the entity returned bysourceto make sure it is a textual response).
At this point the receiver can choose to publish information about this webmention along with any other data it picks up from source.
Asynchronous Status
The status SHOULD be returned by a custom Webmention-Status header. This header SHOULD be the same status codes as would be returned if the request was just submitted.
Request Still Queued
HTTP/1.1 200 OK Webmention-Status: 202
Request Completed Successfully
HTTP/1.1 200 OK Webmention-Status: 200
Request Failed
HTTP/1.1 200 OK Webmention-Status: 400
The response body MAY include a description of the error.
Asynchronous CallBack
Request Completed Successfully
POST /callback/321 HTTP/1.1 Host: bob.host Content-Type: application/x-www-url-form-encoded
status=200
Request Failed
POST /callback/321 HTTP/1.1 Host: bob.host Content-Type: application/x-www-url-form-encoded
status=400& reason=...
The reason paramenter MAY be set to allow for a description of the error.
Error Responses
Sender Error
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.
Possible sender related errors (from the Pingback specification):
- Source URL not found.
- Specified target URL not found.
- Source URL does not contain a link to the target URL.
- Specified target URL does not accept webmentions.
Receiver Error
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.
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
sourcefor the existing webmention. - If it received a 410 on step 2 (performing a
GETrequest onsource) or does not find a link totargetonsource, it SHOULD delete the existing webmention.
Preventing Abuse
- The verification process SHOULD be queued and processed asynchronously to prevent DDoS attacks.
- Receivers SHOULD moderate Webmentions, and if a link is displayed back to the source, SHOULD link to
sourcewithrel="nofollow"to prevent spam. - 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.
Implementations
See IMPLEMENTATIONS
TODO
- Prevention of DDoS
- Malicious attacker could send webmentions to a lot of sites with Alice's site as
sourcewhich will result in a DDoS on Alice's site.
* See this discussion about Refback. 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".
- Malicious attacker could send webmentions to a lot of sites with Alice's site as
- backcompat with v0.1 by also supporting rel="http://webmention.org"?
See also
Let's collaborate
Feel free to file an issue if you have feedback/questions/suggestions.