Another quick one, here is a small library I wrote as part of the Day Job that makes it (slightly) easier to parse web hooks from Mailgun.
Pretty much a stub right now, but we use it daily.
Hopefully it is of use to some folks.
Webmention, as well as the legacy Pingback, provide a way of notifying a third party site that you have made some reference to something on their site. So, for example if I reference somebody elses blogpost in mine, that blog will be notified and my reference may appear as a comment on the post (unless they’re blogging on a passive aggressive silo like Google+ or Facebook, or their blog uses Disqus, which is, in many ways I won’t go into now, the suck).
Pingbacks, and increasingly Webmention, are supported by most major web frameworks and blogging platforms, but adding them to a home rolled platform can be a little bit of a faff, especially if these platforms are build on static HTML.
So, inspired by Pingback.me written by Aaron Parecki, I wrote a bit of middleware that can be installed on a web server with minimal fuss, and can provide pingback/webmention services to other sites.
The reason I didn’t use Pingback.me was that I needed something quickly, I had reasons why I didn’t want to install an entire Ruby stack, and I needed the webhook functionality for a couple of projects (including some funky node.js dataset regeneration to tackle some scalability challenges, but that’s a different story).
One of the main requirements for pingback2hook was ease of setup, which I hope I’ve achieved.
apt-get install apache2 libapache2-mod-php5 couchdb; a2enmod rewrite
RewriteBase in .htaccess.Once you’ve got the software up and running somewhere, you can then start enabling pingback support in your sites. This is a two step process:
[mysite]
secret = "flkjlskjefsliduji4es4iutsiud"
; Zero or more webhook endpoints
webhooks[] = "http://updates.mysite.com"
webhooks[] = "http://data.mysite.com"
// Webmention
header('Link: <http://pingback2hook.myserver.com/webmention/myendpoint/>; rel="http://webmention.org/"');
// Pingback
header('X-Pingback: http://pingback2hook.myserver.com/pingback/myendpoint/xmlrpc');
And/or in the header metadata…
<html>
<head>
<link href="http://pingback2hook.myserver.com/webmention/myendpoint/" rel="http://webmention.org/" />
<link rel="pingback" href="http://pingback2hook.myserver.com/pingback/myendpoint/xmlrpc" />
...
</head>
...
</html>
Once set up, you will get an entry in the database for every pingback or webmention a given permalink receives. If you’ve defined some webhooks, these will be pinged in turn with the JSON content of the ping.
To view your pingbacks you can either make a direct query of the couch database (default: pingback2hook), or make use of the API.
Currently, you can query the API via its endpoint at https://pingback2hook.myserver.com/api/myendpoint/command.format, passing any required parameters on the GET line.
At the time of writing only one command is supported, but I’ll add more as I have need to:
| Command | Parameters | Details |
|---|---|---|
| latest.json|jsonp | target_url, limit (optional), offset (optional) | Retrieve the latest pings or webmentions for a given permalink url. |
To make the query, you need to authenticate yourself. This is done very simply by passing the ‘secret’ for the endpoint in your request header as X-PINGBACK2HOOK-SECRET: mysecret. This is very basic security, and your code is being sent in the clear, so it goes without saying that you should ONLY make queries to the API via HTTPS!
Have a play, and let me know what you think!
As I’ve blogged before, 
IFTTT.com (short for “If This Then That”) is a popular service which lets you trigger actions based on certain events that occur around the internet.
One of the most requested features, by programmers at least, is to add WebHooks support. Webhooks are a very simple way of pinging API information about the internet between web services. It uses JSON to send an arbitrary payload over HTTP via a POST request to a specified endpoint. This is about as simple as you can get, which is of course the beauty of it.
Support for Webhooks is an obvious extension to IFTTT, and would allow people to build on the service, connecting together more than just the hand picked menu of channels on the IFTTT dashboard. Quite why this is so slow coming is a mystery; some have speculated that it was a business decision on their part, others that it is hard to build a slick interface for something of such a highly technical nature, others that they simply haven’t gotten around to it just yet.
Until IFTTT implement a WebHooks channel, you can use the following workaround.
Abhay Rana, in a project over on GitHub, has built a some code which provides a WebHooks bridge for IFTTT and other services. I have extend to add some extra functionality you might find useful.
Currently, the IFTTT wordpress channel uses that software’s RPC endpoint to make posts, so the software works by providing a little bit of middleware, that you install on an internet facing machine, which pretends to be an installation of WordPress. You then point the wordpress IFTTT channel at this installation, passing it some special parameters.
You specify the final endpoint URL as a tag, and by default the contents of the post, title, and categories get JSON encoded and relayed to this endpoint.
Different Webhook endpoints need different fields, however, so my extension lets you provide service specific plugins. These plugins can manipulate the data sent to the upstream endpoint further, providing different fields and encoding options. This lets you support multiple webhook endpoints from a single installation, and without having to set up multiple IFTTT accounts.
To use, create the appropriate plugin in your installation’s plugins directory containing your extension of the Plugin class, then pass a special category “plugin:NameOfClass“.
I have included an example class and a JSON payload class. The latter assumes that the post body is valid JSON, validates it, and then sends it to the upstream endpoint. This lets you send specially crafted messages to upstream webhook endpoints.
My extension also includes much more debug logging, as well as some extra validation code and graceful failures.
IFTTT is a fantastically useful service, but unfortunately you are limited to using the services they choose to (or have time to) write connectors for. I find this limiting, and at times frustrating, since as well as excluding some great existing services, it places limits on my ability to hack my own stuff together!
Previously, I’d often used twitter to glue things together. However, since Twitter are currently making concerted efforts to turn their service into just another ad serving platform, rather than the communication platform and messaging service it was growing into, it was necessary to come up with an alternative method.
WebHooks seem a better solution anyway.
Thanks again to Abhay Rana for the original code, and I hope people find my additions useful!