webmention-implementation-guide

Sending Webmentions

The beauty of simple protocols is that you can do most of this manually very easily.

Given a target to which you want to send a webmention, you need to first discover its webmention endpoint:

curl -i -s $target | grep 'rel="webmention"'

- Note: this is only an approximation, your implementation MUST accept a "webmention" value among the space separated set of terms in the 'rel' attribute. Older implementations may use rel="http://webmention.org/" and some may use both: rel="webmention http://webmention.org/" neither of which are discovered by the grep above. Some may use single quotes (or no quotes at all) to surround the webmention rel value. Still others may only support discovery with an HTTP Link header (e.g. Taproot). Compliant implementations must check the HTTP Link headers for the rel value first, and if not found then parse for the rel value on a <link> or <a> element in the <head> per the HTML specification on parsing rel values.

Now to send the webmention:

curl -i -d "source=$your_url&target=$target_url" $targets_webmention_endpoint

One-liner webmentions

This will send the webmention in a single command:

curl -i -d "source=$your_url&target=$target_url" `curl -i -s $target_url | grep 'rel="http://webmention.org/"' | sed 's/rel="webmention"//' | grep -o -E 'https?://[^ ">]+' | sort | uniq`

See also this gist for sending pingbacks manually: https://gist.github.com/aaronpk/5744879

Endpoint Discovery in PHP

The following code is a set of simple short & flat functions for doing discovery of webmentions in PHP.

Automatic discovery could be implemented in PHP by:

look for a link header using a HTTP request library to get the rels
- link_rel_parser.php :
  - use head_http_rels($url) to curl a HEAD request and from the return value info get back HTTP info["status"] and info["rels"] as a rels array if any.
  - if you already have the raw HTTP header, use http_rels($h) to get a rels array
- and then lookup rels["webmention"] for webmention endpoints
if no Link: for webmention found AND info["type"] == "text/html" or "application/xhtml+xml" then
- use PHP DOMDocument to search the retrieved document for the first <link rel="webmention"> element (or first that matches selector: link[rel~=webmention] ) e.g.:

$w = 0;
$c = curl_init($url);
curl_setopt($c, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
$s = curl_exec($c);

$dom = new DOMDocument();
$dom->loadHTML($s);
$domx = new DOMXPath($dom);
$ws = $domx->query(xphasrel('webmention')); // except with link instead of *
if ($ws) {
  $w = $ws->item(0)->getAttribute('href');
}
// if ($w!=0) then it has a webmention endpoint.
// this code could be changed into a html_webmention_rel($url) function,
// to be called only if head_http_rels($url) returns no "rels" array 
//   or has no "webmention" item(s) in said array

Alternatively see mention-client-php for an object-oriented implementation.

Accepting Webmentions

Currently the easiest way to test consuming webmentions is to implement sending them, then send yourself mentions.

Once you’re ready to test integration with another site, you can either ask someone in IRC to send you a comment, or mention your page in IRC and send a webmention from IRC log URL for that line to your URL.

For example this IRC line links to http://caseorganic.com/notes/2014/02/18/1/. Pasting the URL for the IRC line into the indiewebify.me webmention sender will send webmentions for all the links on the page. Then you can check your page or your server logs to see if the webmention was successful — in this case the comment successfully showed up on the target page.

Resources

checkmention

Main article: Checkmention

Checkmention lets you test your webmention implementation on your indieweb site, and whether it robustly detects certain types of XSS attacks. It also allows you to test for authorship spoofing.

node-webmention-testpinger

node-webmention-testpinger is a tool to ping your site with a variety of webmentions markup. Contains copies of a couple of real world examples of mentions that it enables you to ping locally to a development copy of your site.

node-webmention-testendpoint

node-webmention-testendpoint is tool to test your webmentions client. Generates a demo-post and a demo-endpoint to test if your client parses the webmention-endpoint correctly and to check if the ping body is transmitted correctly.

webmention.rocks

https://webmention.rocks is a test suite that you can use to make sure your Webmention implementation can handle a variety of inputs.

Tutorials

2021-12-13 lqdev.me: Sending Webmentions with F# (archived)
2022-09-23 lqdev.me: Webmentions Request Verification with F#
2022-09-25 lqdev.me: Webmentions Verification with F#