Webmention-developer

 

This page documents technical details of Webmention, specifically for  Webmention developers  so they can support cross-site comments and other responses in their code, or on their site or service.

Webmention is a W3C Recommendation that supersedes Pingback, using a simple HTTP POST request and x-www-form-urlencoded content rather than XML-RPC, with additional functionality (e.g. updates & deletes) as well as greater security & robustness from years of experience with prior iterations.

Get Started Developers
If you already have some idea of what Webmention is and are ready to implement, work your way through: Then: Submit an implementation report for Webmention to help document the growing interoperable decentralized webmention network!
 * https://webmention.rocks/ - Webmention test suite!
 * Instructions: https://github.com/w3c/webmention/tree/master/implementation-reports

Overview
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 information about Bob's post on her site, for example, displaying it as a comment.

Protocol Summary
Specification

If Aaron's blog supports receiving webmentions, and Barnaby's blog supports sending webmentions, then this is how they interact:


 * 1) User Aaron posts a blog post on his blog
 * 2) User Barnaby writes post on his blog that links to Aaron's post.
 * 3) After publishing the post (i.e. it has a URL), Barnaby's server notices this link 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 an HTTP POST request to Aaron's post's webmention endpoint with two parameters:
 * 6) *  set to Barnaby's post's permalink
 * 7) *  set to Aaron's post's permalink.
 * 8) Aaron's server receives the webmention
 * 9) Aaron's server verifies that   in the webmention is a valid permalink on Aaron's blog (if not, processing stops)
 * 10) Aaron's server verifies that the   (when retrieved, after following redirects) in the webmention contains a hyperlink to the   (if not, processing stops)

What to do with the webmention once processed is unmentioned in the spec but implied (and vaguely mentioned in the pingback spec). Aaron's server can display the information about Barnaby's post somewhere on Aaron's post.

The most popular display is to display Barnaby's post as a comment, however, how to display can vary based on what Barnaby posted, or Aaron's preferences for display. For more:
 * See responses: displaying responses
 * See comment: how to display

How to implement sending
Every time you:
 * create a post, send Webmentions to every link in the post
 * update a post, send Webmentions to every link in the post before the update and after the update
 * delete a post, send Webmentions to every link that was in the post

To send a Webmention to a link:
 * do Webmention endpoint discovery on that link
 * send a Webmention using the endpoint, source= your page with the link, target= the link

How to implement receiving
(stub)
 * set up a Webmention endpoint to receive them for you
 * add Webmention endpoint discovery link to your post permalinks and any other pages you wish to receive webmentions for, like your homepage
 * validate and process received Webmentions for what type it is (like a reply, like, repost, or other response), and whether it is new, an update, or a notification of deletion.
 * display received comments, likes, reposts, and other responses

How to test
(stub)
 * Webmention.rocks
 * webmention_server.py dummy http server for local testing - both receives and sends webmentions
 * Useful for local webmention testing

How to send webmentions with cURL
Manually sending a webmention with cURL can be the quickest way for developers to test webmentions.

When your source URL links to a target URL:


 * 1) Find the target's webmention endpoint. This may be in the HTML or in an HTTP Link header, with
 * 2) Using the source, target, and endpoint URLs, enter at the command line:

Implementations
See IndieWeb Examples

Libraries


Go

 * go-jamming - a microserver that is capable of automatically sending and receiving mentions based on your RSS feed
 * willnorris.com/go/webmention - client library and command-line tool for discovering and sending webmentions.

Elixir

 * ckruse/webmentions-elixir - client library for discovering and sending webmentions.

Node.js

 * glennjones/webmentions - a helper library for endpoint discovery, pulling validating webmentions and sending webmention requests
 * remy/wm (webmention.app) - client for sending webmentions for entries in your feed

Perl

 * Web::Mention - library for both sending webmentions and processing received webmentions

PHP

 * indieweb/mention-client-php - library for sending webmention and pingpack notifications
 * phpish/webmention - Simple webmention client (non-OO) packaged as a Composer package.
 * pear2/Services_Linkback - pingback+webmention client + server library

Python

 * vrypan/webmention-tools - client library and command line webmention sender
 * ronkyuu - client library and command-line tools
 * snarfed/webutil (webmention.py) - library for discovering endpoints and sending webmentions, small but complete

Ruby

 * indieweb/webmention-client-ruby - library for sending webmention notifications

Emacs Lisp

 * wkearn/webmentions - library for endpoint discovery and sending webmentions from Emacs

.NET

 * WebmentionFs - Library for Webmention endpoint discovery, sending, and receiving.

Discovery
For webmention endpoint discovery:

Elixir

 * ex_http_link - Elixir Link header (RFC 5988) parser

Haskell

 * http-link-header - Haskell Link header (RFC 5988) parser

PHP

 * link_rel_parser -  &   - HTTP header string parser for RFC5988 Link: rels (including  ) & function to curl a HEAD request and parse it all in one.
 * and get_rel_webmention (in same library) -  - calls aforementioned functions to obtain first webmention (if any) and pingback (if any) endpoints.
 * phpish/link_header - Link header (RFC 5988) parser
 * PEAR: HTTP2 - Link header (RFC 5988) parser (documentation)
 * php-webmention-endpoint-discovery - library for discovering a webmention endpoint, includes experimental support for the often forgotten DNS checks mentioned in the spec

Python

 * ronkyuu - client library and command-line tools
 * snarfed/webutil (webmention.py) - library, small but complete

Ruby

 * link_rel_parser - Link header (RFC 5988) parser (port of link-rel-parser-php)
 * indieweb-endpoints-ruby - gem for discovering IndieWeb endpoints

.NET

 * WebmentionFs - Library for Webmention endpoint discovery, sending, and receiving.

Handling
Handling receiving webmentions, listed by programming language / server:

Go

 * go-jamming - a microserver that is capable of automatically sending and receiving mentions based on your RSS feed
 * webmentiond - a daemon with UI for moderation

PHP

 * Minimum Viable Webmention handler: https://gist.github.com/adactio/6484118
 * pear2/Services_Linkback - pingback+webmention client + server library
 * iw-utils described by Jan Boddez as 'a (for now) basic Webmention endpoint.'

Perl

 * Web::Mention - library for both sending webmentions and processing received webmentions

Node.js

 * webmention-verifier verifier. Handles mentions with arbitrary response types
 * webmention-handler webmention processing framework. Handles WebMentions asynchronously in nodejs with typescript support.

nginx

 * Nothing but nginx configuration
 * Nothing but nginx configuration

.NET

 * WebmentionFs - Library for Webmention endpoint discovery, sending, and receiving.

Parsing
For parsing the mentions, the following may come in handy:


 * microformats2 implementations and parsers
 * php-mf-cleaner - "Takes microformats2 array structure and makes it more sane. Counterpart to indieweb/php-mf2"
 * went - Webmention Endpoint Tools, a Python library that takes source and target URLs and does the rest of the job for you.
 * kaku - Python Flask app that handles webmentions using ronkyuu

Notifications
The following tools show how a notification could be sent upon receiving a webmention
 * PHP to email
 * https://gist.github.com/otherjoel/9301d985622f0d3d1a09
 * Javascript
 * bear is working on this...
 * XMPP
 * webmention.io can do this
 * - bear is working on this...

Ruby

 * webmention-verification-ruby - Ruby gem for verifying a received webmention

.NET

 * WebmentionFs - Library for Webmention endpoint discovery, sending, and receiving.

Resources

 * How to test webmentions: Implementation Guide
 * Implementation Details
 * FAQ : Please read this before filing an issue or adding to brainstorming
 * Issues
 * Brainstorming

Page To Do
Edits / improvements for this page in particular:
 * Simplify this page for web developers
 * simplify prose
 * Re-order content as needed to to
 * motivate web developers first
 * provide the simplest, easiest thing to implement first
 * then the next simplest/easiest but still useful, etc.
 * provide illustrative diagrams for protocol overview, how tos
 * perhaps write up a developer-centric section
 * figure out how to integrate this with IndieMark

Edits to Webmention:
 * keep analyzing, asking, doing:
 * How can the Webmention page be simplified to quickly:
 * make sense to generations 1-3
 * motivate generations 1-3 that they want Webmentions on their site(s)
 * Add clear instructions for enabling Webmentions with full POSSE/backfeed support with the goal of all responses to your content on social media goes back to your site, whether it uses:
 * Known
 * WordPress (depends on simpler plugin strategy? like just one instead of two)
 * Provide inspirational screenshots / diagrams of Webmention potential, e.g.
 * marginalia