Webmention-developer

From IndieWeb
Jump to: navigation, search


webmention-logo.svg

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.

Submit an implementation report for Webmention to help document the growing interoperable decentralized webmention network!

w3c-spec-REC.svg

Contents

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

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

(stub)

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)

Implementations

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)

aaronparecki-webmention-display.png

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/"

waterpigs-webmention-display.png


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

adactio-webmention-display.png

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.

barryfrost-webmention-display.png

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.

kartikprabhu-fragmention-display.png

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

jeena.net-webmention-comments-display.png

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.

kryogenix-webmention-comment-display.png

Giovanni Parra with Jekmentions

  • Giovanni T. Parra receiving webmentions on fiatjaf.alhur.es as of 2015-02-28.
    • Wrote Jekmentions, a small service that works as a webmention endpoint for Jekyll sites hosted on GitHub that sends the webmentions received as files in commits to the GitHub repository.
    • Webmentions are sent manually for now. Some are being sent, but only through brid.gy to twitter.

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

Peter Molnar with WordPress

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

seblog-webmention-comment.png

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

Libraries

Sending

For webmention endpoint discovery:

Handling

Handling receiving webmentions:

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

Notifications

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

Publishing Software

Some open source publishing software supports webmentions:

  • Known personal publishing software sends webmentions and accepts webmention comments (including webmention updates), and likes
  • FrancisCMS personal publishing software similarly sends and receives
  • WWWTech personal publishing software similarly sends and receives
  • phorkie sends and accepts webmentions to notify remote instances about forks

Some additional publishing software, portions of which are open source, supports webmentions:

  • p3k sends webmentions for all posts and accepts webmention comments on events, notes, replies, RSVPs
  • Taproot
  • Falcon sends webmentions for all links in posts (except maybe articles - untested)

Plugins exist for some open source publishing software:

Services

Some services one can use to receive or send webmentions. Alphabetical.

Bridgy

Main article: Bridgy

brid.gy is a service that sends webmentions for comments/replies, likes, and reposts on Facebook, Twitter, Google+, and Instagram posts. It uses original post discovery to find target links for the webmentions. GitHub repo here.

Bridgy Publish also supports webmention as a mechanism to trigger POSSEing to Facebook, Twitter, and Instagram.

bridgy example screenshot.png

mention-tech

Main article: mention-tech

mention-tech is a service that can receive webmentions on behalf of anyone via both webmention directly, and a web form on its home page.

stapibas

stapibas is a self-hosted service to send and receive webmentions for websites and blogs.

It can be used to send out webmentions and pingbacks for new posts on static sites.

Telegraph

Telegraph is an open source project and hosted service for sending webmentions and pingbacks. You can use it to send mentions to all links on a page, or send a webmention with specific source and target.

webmention.herokuapp.com

Main article: webmention.herokuapp.com

webmention.herokuapp.com is an open-source project and hosted service for receiving webmentions for registered sites and allowing those to be displayed through javascript.

webmention.io

Main article: webmention.io

webmention.io is an open-source project and hosted service for receiving webmentions and pingbacks on behalf of your indieweb site.

Tools

Tools you can install to send webmentions

Firefox Addon

Resources

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

Personal tools
Namespaces
Variants
Actions
Recent & Upcoming
Resources
Toolbox