From IndieWeb
Jump to: navigation, search

Webmention Rocks

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 only HTTP 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!


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

Main article: webmention-spec

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 a webmention to Aaron's post's webmention endpoint with
    • source set to Barnaby's post's permalink
    • target set to Aaron's post's permalink.
  6. Aaron's server receives the webmention
  7. Aaron's server verifies that target in the webmention is a valid permalink on Aaron's blog (if not, processing stops)
  8. Aaron's server verifies that the source (when retrieved, after following redirects) in the webmention contains a hyperlink to the target (if not, processing stops)

Unmentioned but implied (and vaguely mentioned in the pingback spec):

  • Aaron's server displays the information about Barnaby's post somewhere on Aaron's post.
  • If a u-url is present at the source, then the receiver could display that URL, and default to showing the source otherwise. This allows services like Bridgy to render the original tweet URL in the u-url property so receivers will link to the tweet instead of the Bridgy proxy page.

See comment: how to accept a comment for more details on accepting comments in general and displaying them.

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


  • 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


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 rel=webmention
  2. Using the source, target, and endpoint URLs, enter at the command line:
    curl -i -d source=source -d target=target endpoint


IndieWeb Examples

The following users/sites have live implementations for sending and or receiving webmentions, listed in rough chronological order of when they did so.

For past implementations that are no longer live, see Previous Examples.

If you add Webmention sending or receiving to your site, add yourself in a new section at the bottom of this list and link to your site, implementation(s), and permalinks of your webmention receiving/sending posts. Try to include a screenshot that shows that too.

Aaron Parecki with p3k

  • Aaron Parecki using p3k on aaronparecki.com as of 2013-05-26. Details:
    • All posts send webmentions (as of 2013-05-26 first (semi-)automatic webmention sent on 2013-03-31) upon posting (asynchronously with posting UI, no results reported).
    • Events, notes (including RSVPs), replies accept webmentions (as of 2013-05-26)
    • Discovery with both: rel="webmention" and rel="http://webmention.org/" links in head, and HTTP Link: rel="http://webmention.org/ header
    • Posts have an input form for pasting in your comment URL to conveniently send a manual webmention (as of 2013-10-12)


Ben Werdmuller with Known

  • Ben Werdmuller using Known (idno ) on werd.io as of 2013-05-31. Details:
    • All(?) posts send webmentions as of 2013-05-31 and accept as of 2013-06-??
    • Discovery with both: rel="http://webmention.org/" and rel="webmention" links in head, and with HTTP Link: <http://werd.io/webmention/>; rel="webmention"

Barnaby Walters with Taproot

  • Barnaby using Taproot on waterpigs.co.uk as of 2013-06-11 (per git). Details:
    • All notes and articles accept (as of 2013-06-20) and send webmentions (as of 2013-06-11) upon posting (posting UI returns response content to the browser, then synchronously sends webmentions)
    • Incoming webmentions for notes and articles are parsed and stored, displayed for notes (comment updating as of 2013-06-23) but not yet articles
    • Discovery only with HTTP Link: <http://waterpigs.co.uk/mentions/webmention/>; rel="http://webmention.org/"


Jeremy Keith with adactio.com

  • Jeremy Keith on adactio.com as of 2013-09-15. Details:
    • All blog posts accept webmentions
    • Discovery only with: rel="webmention" link in head
    • Blog posts have an input form for pasting in your comment URL to conveniently send a manual webmention


Barry Frost with barryfrost.com

  • Barry Frost on barryfrost.com as of 2013-09-15[1][2]. Details:
    • All(?) posts send and accept webmentions
    • Discovery with: rel="webmention" link in head, and HTTP Link: <http://barryfrost.com/webmention>; rel="webmention" in header
    • Posts have a hyperlink in footer "How to comment on this post" to instructions detailing posting an h-entry with h-card and how to send a webmention.


Calum Ryan with calumryan.com

  • Calum Ryan on calumryan.com
    • Since 2016-08-28 support for receiving webmentions using jekyll-webmention_io initially on purely Jekyll generated pages but now also on notes generated from self-built CMS in PHP
    • Since 2016-11-06 built in function for manual sending of webmentions via self-built CMS in PHP using mention-client-php

Christian Weiske with stapibas

  • Christian Weiske receiving webmentions on cweiske.de as of 2013-10-22. Details:
    • All posts accept webmentions using stapibas
    • Discovery only with HTTP Link: <http://cweiske.de/stapibas/xmlrpc.php>; rel="webmention"
    • Approach for sending webmentions (with fallback sending of pingbacks)
      • https://github.com/pear2/Services_Linkback/blob/master/src/PEAR2/Services/Linkback/Client.php#L236
      • check self Atom feed, if there are updates then proceed with discovery/sending for each update, for each link in the update: do a HEAD request first, do discovery for webmention endpoint, if none found, do discovery for pingback endpoint, if none found and the resource is 'application/xhtml+xml' or 'text/html', do a GET request, do discovery for webmention endpoint, if none found, do discovery for pingback endpoint. send webmention if an endpoint was found, otherwise send pingback if an endpoint was found.

Bear with bear.im

  • Bear on bear.im as of 2013-12-01.
    • All posts accept webmentions and send webmentions for new and updated posts
    • Full Discovery for link headers, links in html head and body
    • webmention handling done by the Python library ronkyuu

Kartik Prabhu with kartikprabhu.com

  • Kartik Prabhu on kartikprabhu.com as of 2013-12-03.
    • All articles & notes accept webmentions
    • Articles have an input form for sending a manual webmention inspired by adactio.com. The form prompt links to the webmention endpoint.
    • Webmentions are saved as responses and appear below the article classified according to response type.
    • Webmentions are sent manually for all posts.


Pelle Wessman with webmention.herokuapp.com

Jeena with jeena.net

  • Jeena Paradies using a home grown Rails app on https://jeena.net as of 2013-12-06. Details:
    • All homepage, blog posts and notes, photos, comments and events accept webmentions
    • Discovery with: rel="webmention" Link: in HTTP header
    • Sends webmentions on create, update and delete, no salmentions yet
    • Has a manual form
    • Homepage receives webmentions and notifies him per email


Christian Kruse with wwwtech.de

  • Christian Kruse using a home grown Phoenix app on https://wwwtech.de as of somewhen in 1998. Details:
    • All homepage, blog posts and notes, photos, comments accept webmentions
    • Discovery with rel="webmention" in HTTP header and HTML document
    • Sends webmentions on create and update, no salmentions yet

Andy Sylvester with WordPress Webmention plugin

gRegor Morrill with ProcessWire plugin

  • gRegor Morrill sending and receiving webmentions on gRegorLove.com as of 2014-02-04.
    • Using a custom plugin I developed for ProcessWire; previously a plugin for Nucleus CMS
    • All articles can receive webmentions
    • Webmention endpoint is broadcast via Link: HTTP header and <link> element
    • Incoming webmentions validate the target is a valid URL on gregorlove.com and the post ID in the URL is valid.
    • Webmentions are parsed and further validated asynchronously. Replies/mentions are displayed interleaved with "local" blog comments..
    • More implementation notes

Glenn Jones with node webmentions module

  • Glenn Jones using node.js module github.com/glennjones/webmentions on glennjones.net as of 2014-02-19.. Details:
    • All notes accept webmentions
    • Discovery only with: rel="webmention" link in head
    • The notes editor has an input for the in-reply-to URL
    • The webmentions module allows pinging of webmention between any sites
    • Yet to implement: full authorship parsing, updates, deletes.

David Shanske with WordPress plugin

Ben Roberts with ben.thatmustbe.me

  • Ben Roberts sending and receiving webmentions on ben.thatmustbe.me as of 2014-04-24
    • Parsing replies, mentions, and likes. Rsvps are handled as just mentions currently.
    • Discovery with both: rel="webmention" and rel="http://webmention.org/" links in head, and HTTP Link: rel="http://webmention.org/ header
    • Currently uses vouch and a whitelist while all others are sent to moderation.
    • Processing happens asynchronously by cron job.
    • Submissions return a link for queue record that returns a status as a Webmention-Status header as well as a minor note in the body.
    • Attempting to keep implementation notes as a modified spec at webmetion0.2-b1
    • Sending is done automatically when post is made.

Will Norris with webmention.herokuapp.com

Joel Dueck with thelocalyarn.com

  • Joel Dueck receiving webmentions on thelocalyarn.com as of 2014-09-23.
    • All posts accept webmentions as well as traditional comments.
    • Webmentions (if valid) are logged to a text file and sent to Joel via email. Those that pass moderation are manually added to the target post as a comment (which on this site means it is included in the blog and sent to email and RSS subscribers as well as being appended to the target post).
    • Endpoint is a modified version of Jeremy Keith's webmention.php.
    • Webmentions sent manully. More to implement. To-do list is long. Site is running Textpattern CMS, so a complete webmentions plugin is both feasible and ideal.

Dan Lyke with www.flutterby.com

  • Dan Lyke receiving webmentions on Flutterby.com blog entries as of 2014-10-10.
    • Webmention endpoint is broadcast via <link> element and <indie-action> element.
    • Currently only displays links on title text back to source URLs

Johnny Oskarsson with joskar.se

  • Johnny Oskarsson receiving webmentions on joskar.se as of 2014-10-23.
    • Webmention endpoint is broadcast via Link: HTTP header only.
    • Pages marked up with h-entry in-reply-to show up as comments, others won't show up at all. (but they will be logged)
    • Webmentions are sent manually for now.

Stuart Langridge with Pelican additions

  • Stuart Langridge sending and receiving webmentions on kryogenix.org as of 2014-11-29.
    • Write up linking to various bits of code for Pelican, the Python static site generator, at "Enabling Webmentions".
    • Webmention endpoint is declared in the HTML with a <link> element, because HTTP headers are a pain in the behind to set up by comparison.
    • Uses Pelle Wessman's webmention Heroku endpoint as endpoint, and then some Python to fetch and bake in webmentions on site regeneration, and some JS to pull them in live.


Tantek with Falcon

Tantek Çelik using Falcon on tantek.com sends webmentions automatically as of 2015-06-11 specifically for the following kinds of links:

Alex Kearney with IndieAnndroid

Jason Garber with FrancisCMS

  • Jason Garber using FrancisCMS on sixtwothree.org as of 2016-01-27. Details:
    • All posts, links, and photos automatically accept webmentions. Replies, shares, and likes are reverse syndicated via Bridgy.
    • Post, link, and photo permalink pages have an input form for pasting in your comment URL to manually send a web mention.
    • Discovery with: Link: <https://sixtwothree.org/webmentions>; rel="webmention" HTTP header and <link rel="webmention" href="https://sixtwothree.org/webmentions"> in the HTML's <head>.
    • Webmention source URLs are parsed using the microformats2 Ruby gem.

Jay Robinson with aruna

  • j4y_funabashi on j4y.co as of 2016-06-13.
    • All new posts send webmentions
    • passes all 21 Discovery tests on webmention.rocks
    • receiving sort of works but I don't display anything yet and there are bugs that sometimes spam brid.gy

Sebastiaan Andeweg on seblog.nl


fluffy on beesbuzz.biz

  • fluffy, implemented/working as of November 2018
    • Uses webmention.io as the endpoint and webmention.js to display them client-side
    • Uses Pushl to send outgoing, with both a git commit hook and a regular cron job

Previous Examples

Sandeep Shetty

Sandeep Shetty used Converspace. The domain now redirects, however based on git commit history and archived links:

  • 2013-06-04: added ability to send webmentions [3]
  • 2013-06-09: added ability to receive webmentions [4]
  • 2013-06-11: received a webmention from Aaron Parecki and displayed it as a comment. [5] [6]
    • It appears this is the first federated comment thread using webmention and h-entry



For webmention endpoint discovery:


Handling receiving webmentions:

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


The following tools show how a notification could be sent upon receiving a webmention



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
    1. motivate web developers first
    2. provide the simplest, easiest thing to implement first
    3. 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:
    1. How can the Webmention page be simplified to quickly:
      1. make sense to generations 1-3
      2. motivate generations 1-3 that they want Webmentions on their site(s)
    2. 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:
      1. Known
      2. WordPress (depends on simpler plugin strategy? like just one instead of two)
    3. Provide inspirational screenshots / diagrams of Webmention potential, e.g.

See Also