Hooray, Webhooks

Webhooks are “user-defined HTTP callbacks” brought by Jeff Lindsay. While it’s augmented for some time, it comes to my sight because of continuous integration like Travis CI at GitHub. Later, Slack made it fancy as every services could pop up messages in the channel as if I was in Enterprise bridge:

It’s also interesting to discover how it can be implemented on Ruby on Rails.

Case Study: Webhooks at GitHub and Slack

Since GitHub and Slack build great webhooks, it’s a good practice to see how they build the service.

GitHub

GitHub runs central repositories for git and origination services. It offers webhooks on organization level and repositories level where user can manage webhooks in the admin panel. GitHub allow users to create “up to 20 webhooks for each event on each installation target”. has an Integrations Directory

Events are triggered on certain scenario: (highlight)

Illustrated in adding webhook page on the admin panel:

With pre-set configuration, GitHub is responsible for sending payload (JSON) based on event type.

However, the payload size will be small than 5MB, otherwise, it will be discarded. It’s user’s responsibility to monitor payload size.

A HTTP header of webhooks includes event name, unique ID and signature by HMAC hex digest of the payload which uses hook’s secret as a key if secret is set.

GitHub build a great API. Webhook can be managed by its API. For testing reason, GitHub provides a Ping event to test a hook, hook’s test endpoint.

Service hooks are defined sets of webhooks by the third party at github-services repo. However, GitHub no longer accepts new service instead of urging new integration service to build OAuth application help managing webhooks. Be noted, GitHub integrations directory is different than services. It’s just a directory to help redirecting to third party services who manage webhooks.

PubSubHubbub

This crazy name (PubSubHubbub) belongs to an open protocol for distributed publish/subscribe communication on the Internet. Their specification defines a decoupled flow for webhooks.

A Wordpress plugin helps you announce new blog post. And GitHub can serve as a PubSubHubbub hub for all repositories.

It’s designed to overcome polling for getting feed updates. GitHub will create a webhook if you request the hub.

Slack

Slack builds the fancy messaging app for teams. Many integrations and bots are just favorable.

Basically, Slack offers incoming and outgoing webhooks. Slash commands is built on these two webhooks.

In terms of incoming webhooks, sending a JSON payload and plain text to a hashed url would trigger a message with defined name and icon. Simple as that. Outgoing webhooks come with receiving payload of messages. A payload will be sent when triggered by keywords or a new message on the channel. The integrated services can reply back if they want.

As an extension of outgoing webhooks, slash commands send payload to server and reply messages back to the channel. However, bots are separated from other webhooks. They build upon Slack API and realtime API.

Considerations

Webhooks are highly application-specific. Event payloads would be transported in secure (HTTPS) or plaintext (Don’t care) manner according to the content. Therefore, signature (symmetric key) or a token can be used as a way to authentication. For ambitious applications, they offers a way to package webhooks as a service to minimize the deployment cost of webhooks.