Webmention-developer

From IndieWeb


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

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:
    • 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)

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)

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

Implementations

See IndieWeb Examples

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

Node.js

Perl

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

PHP

Python

Ruby

Emacs Lisp

.NET

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

Discovery

For webmention endpoint discovery:

Elixir

Haskell

PHP

Python

Ruby

.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

Perl

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

Node.js

nginx

.NET

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

Parsing

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

Verification

Ruby

.NET

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

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

Retrieved from "https://indieweb.org/wiki/index.php?title=Webmention-developer&oldid=85229"