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:
- https://webmention.rocks/ - Webmention test suite!
Then: Submit an implementation report for Webmention to help document the growing interoperable decentralized webmention network!
Overview
A typical Webmention flow is as follows:
- Alice posts some interesting content on her site (which is set up 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 by the URL of Bob's post.
- 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
If Aaron's blog supports receiving webmentions, and Barnaby's blog supports sending webmentions, then this is how they interact:
- User Aaron posts a blog post on his blog
- User Barnaby writes post on his blog that links to Aaron's post.
- After publishing the post (i.e. it has a URL), Barnaby's server notices this link as part of the publishing process
- Barnaby's server does webmention discovery on Aaron's post to find its webmention endpoint (if not found, process stops)
- Barnaby's server sends an HTTP POST request to Aaron's post's webmention endpoint with two parameters:
source
set to Barnaby's post's permalinktarget
set to Aaron's post's permalink.
- Aaron's server receives the webmention
- Aaron's server verifies that
target
in the webmention is a valid permalink on Aaron's blog (if not, processing stops) - Aaron's server verifies that the
source
(when retrieved, after following redirects) in the webmention contains a hyperlink to thetarget
(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:
How to
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:
- Find the target's webmention endpoint. This may be in the HTML or in an HTTP Link header, with
rel=webmention
- Using the source, target, and endpoint URLs, enter at the command line:
curl -i -d source=source -d target=target endpoint
Implementations
Libraries
Sending
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_rels($h)
&head_http_rels($url)
- HTTP header string parser for RFC5988 Link: rels (includingX-Pingback
) & function to curl a HEAD request and parse it all in one.- and get_rel_webmention (in same library) -
get_rel_webmention($url)
- calls aforementioned functions to obtain first webmention (if any) and pingback (if any) endpoints.
- and get_rel_webmention (in same library) -
- 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 (
u-*
) - webmention-handler webmention processing framework. Handles WebMentions asynchronously in nodejs with typescript support.
nginx
- 2020-01-10 : A static, manual system for *receiving* webmentions (and pingback) with nginx (archived)
- 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
- Javascript
- bear is working on this...
- XMPP
- webmention.io can do this
- - bear is working on this...
Verification
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 #Why 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:
- Provide inspirational screenshots / diagrams of Webmention potential, e.g.
- How can the Webmention page be simplified to quickly: