Debugging Webhooks

Debugging Webhooks

A webhook is a very common design pattern for HTTP APIs. Webhooks provide an elegant mechanism for developers who are interested in changes happening “rarely” on an HTTP resource (or API). They are sometimes called callback URL.

In the context of PubSubHubbub (and Superfeedr, by extension), A 3rd party developer wants to know when a new entry has been added to a feed. The subscription mechanism (sometimes called registration) allows the 3rd party developer to provide an HTTP url which will receive a POST request when the feed has been updated.

Debugging webhooks is not always obvious because the process is usually asynchronous: the 3rd party developer (subscriber) has to wait for the resource to be updated.

Triggering Updates

Superfeedr provides 2 mechanisms to troubleshoot your callback urls. The first one is a simple application which mimicks a publishing tool. It lets you add messages to a feed. The feed is a PubSubHubbub publisher which means that as soon as you click the submit button, the feed is updated, the hub is notified and each subscriber’s webhook is called.

Another tool that we provide is called replay notifications. Once you’re subscribed to a feed, you can easily replay previous notifications. This is very convenient to troubleshoot your webhooks.

The docs give you some details, but here’s an example.

curl -X GET 'http://push.superfeedr.com/'
-u demo:demo
-d'hub.mode=replay'
-d'hub.topic=https://superfeedr-blog-feed.herokuapp.com/'
-d'hub.callback=http://my.webhook/path'
-D-

Immediately after this call, the webhook will be triggered with the content of the latest entry in our blog’s feed.

Inspecting Content

Once you can easily reproduce and trigger notifications, you should start inspecting the content of the notifications. Most languages used to create web application will let you log the HTTP headers and the body of the notification, but you could also use applications created for that purpose such as WebhookInbox or Requestbin.

Both application let you create disposable webhooks and they both support PubSubHubbub’s verification mechanism.

Once a webhook is triggered, they will log the complete request (headers and body). You can then easily inspect it and see exactly what your code received.

See also:

Liked this post? Read the archive or

On the same topic, check replaying notifications, http raw body and ping me i'm famous.

Previously, on the Superfeedr blog: Feed-Id in User Agents.