You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A modern alternative to [Pingback](http://www.hixie.ch/specs/pingback/pingback).
4
4
5
+
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.
6
+
7
+
8
+
## Editors
9
+
Sandeep Shetty (sandeep.shetty@gmail.com)
10
+
11
+
__NOTE__: All contributions to this specification are released into the public domain.
12
+
13
+
14
+
## Introduction
15
+
16
+
Here's a typical webmention flow:
17
+
18
+
1. Alice posts some interesting content on her site (which is setup to receive webmentions).
19
+
2. Bob sees this content and comments about it on his site, linking back to Alice's original post.
20
+
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.
21
+
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.
`bobs.host` SHOULD check that `target` is a valid resource belonging to it and then perform a `GET` on `source` and confirm that it actually links to `target`.
41
-
42
-
**Note**: Might look for [rel="in-reply-to"](http://microformats.org/wiki/comment-brainstorming#hAtom_and_in-reply-to), or just the link itself somewhere on the page.
43
-
44
-
## Response
45
-
46
-
### Success
47
-
48
-
If the WebMention request was successful, the server MUST reply with an `HTTP 202 Accepted` response code. The body of the response is left undefined, but is recommended to return a message indicating the pingback was successful and should respect the content-type of the `Accept` header. If no `Accept` header is present, an HTML success body may be returned. It is also valid to not send any body in the response.
49
-
50
-
For example, typical responses may look like the following:
51
-
52
-
#### HTML
53
-
54
-
```http
55
-
POST /webmention-endpoint HTTP/1.1
56
-
Host: bobs.host
57
-
Content-Type: application/x-www-url-form-encoded
58
55
59
-
source=http://alices.host/alice/post/42&
60
-
target=http://bobs.host/bob/post/2
56
+
http://alice.host/webmentions/222
61
57
```
62
-
```http
63
-
HTTP/1.1 202 Accepted
64
-
Content-Type: text/html
65
58
66
-
<!DOCTYPE html>
67
-
<html>
68
-
<head>
69
-
<title>WebMention</title>
70
-
</head>
71
-
<body>
72
-
<p>WebMention was successful</p>
73
-
</body>
74
-
</html>
75
-
```
59
+
`202 Accepted` is the recommended status code to return indicating that the request SHOULD be queued and processed asynchronously to prevent __DDOS attacks__. The response body SHOULD include a URL that can be used to monitor the status of the request.
76
60
77
-
#### JSON
61
+
If you choose to process the request and perform the [verification](#verification) step synchronously, you can respond with a `200 OK` status on success.
78
62
79
-
```http
80
-
POST /webmention-endpoint HTTP/1.1
81
-
Host: bobs.host
82
-
Content-Type: application/x-www-url-form-encoded
83
-
Accept: application/json
63
+
See [Error Responses](#error-responses) for what to do when the webmention is not successful.
84
64
85
-
source=http://alices.host/alice/post/42&
86
-
target=http://bobs.host/bob/post/2
87
-
```
88
-
```http
89
-
HTTP/1.1 202 Accepted
90
-
Content-Type: application/json
91
65
92
-
{
93
-
"result": "WebMention was successful"
94
-
}
95
-
```
96
66
67
+
### Verification
68
+
1. The receiver SHOULD check that `target` is a valid resource belonging to it and that it accepts webmentions.
69
+
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
70
98
-
### Errors
71
+
At this point the receiver can choose to publish information about this webmention along with any other data it picks up from `source`.
99
72
100
-
In addition to the standard HTTP status codes that may be returned for things like malformed requests, WebMention defines several error cases that must be handled.
101
73
102
-
All errors below MUST be returned with an `HTTP 400 Bad Request` response code.
74
+
#### Error Responses
103
75
104
-
*`source_not_found`: The source URI does not exist.
105
-
*`target_not_found`: The target URI does not exist. This must only be used when an external GET on the target URI would result in an `HTTP 404` response.
106
-
*`target_not_supported`: The specified target URI is not a WebMention-enabled resource. For example, on a blog, individual post pages may be WebMention-enabled but the home page may not.
107
-
*`no_link_found`: The source URI does not contain a link to the target URI.
108
-
*`already_registered`: The specified WebMention has already been registered.
76
+
##### Sender Error
109
77
110
-
The format of the error body should respect the content-type in the `Accept` header. If no `Accept` header is present, it is acceptable to return an HTML body with a description of the error.
78
+
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 simple plain text description of the error in the response body.
111
79
112
-
#### HTML
80
+
Possible `sender` related errors (from the [Pingback](http://www.hixie.ch/specs/pingback/pingback) specification):
81
+
* Source URL not found.
82
+
* Specified target URL not found.
83
+
* Source URL does not contain a link to the target URL.
84
+
* Specified target URL does not accept webmentions.
113
85
114
86
```http
115
87
POST /webmention-endpoint HTTP/1.1
116
-
Host: bobs.host
88
+
Host: alice.host
117
89
Content-Type: application/x-www-url-form-encoded
118
90
119
-
source=http://alices.host/alice/post/42&
120
-
target=http://bobs.host/bob/post/2
91
+
source=http://bob.host/post-by-bob&
92
+
target=http://alice.host/post-by-alice
121
93
```
122
94
```http
123
95
HTTP/1.1 400 Bad Request
124
-
Content-Type: text/html
125
96
126
-
<!DOCTYPE html>
127
-
<html>
128
-
<head>
129
-
<title>WebMention Error</title>
130
-
</head>
131
-
<body>
132
-
<h2>no_link_found</h2>
133
-
<p>The source URI does not contain a link to the target URI</p>
134
-
</body>
135
-
</html>
97
+
Source URL does not contain a link to the target URL.
136
98
```
137
99
138
-
#### JSON
100
+
##### Receiver Error
101
+
102
+
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 simple plain text description of the error in the response body.
139
103
140
104
```http
141
105
POST /webmention-endpoint HTTP/1.1
142
-
Host: bobs.host
106
+
Host: alice.host
143
107
Content-Type: application/x-www-url-form-encoded
144
-
Accept: application/json
145
108
146
-
source=http://alices.host/alice/post/42&
147
-
target=http://bobs.host/bob/post/2
109
+
source=http://bob.host/post-by-bob&
110
+
target=http://alice.host/post-by-alice
148
111
```
149
112
```http
150
-
HTTP/1.1 400 Bad Request
113
+
HTTP/1.1 500 Internal Server Error
151
114
152
-
{
153
-
"error": "no_link_found",
154
-
"error_description": "The source URI does not contain a link to the target URI"
155
-
}
115
+
Cannot processes webmentions at this time. Please try again later.
156
116
```
157
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 failed on step 2, that is, it got a 404 while performing a `GET` request on `source` or does not find a link to `target`, it SHOULD delete the existing webmention.
122
+
158
123
159
124
160
-
## Preventing Spam and Abuse
161
-
* The verification process SHOULD be queued to prevent DDOS attacks.
162
-
* WebMention receivers SHOULD moderate WebMentions, and if a link is displayed back to the source, SHOULD link to `source` with `rel="nofollow"` to prevent spam.
163
-
* Receivers MAY periodically re-verify that `source` links to `target`, and remove visible links if source no longer links to target.
125
+
## Preventing Spam/Abuse and Security considerations
126
+
* The verification process SHOULD be queued and processed asynchronously to prevent DDOS attacks.
127
+
* Receivers SHOULD moderate Webmentions, and if a link is displayed back to the source, SHOULD link to `source` with `rel="nofollow"` to prevent spam.
128
+
* Receivers MAY periodically re-verify webmentions and [update them](#updating-existing-webmentions).
129
+
* 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.
0 commit comments