Hello!

I am pleased to announce one of the new features which will be shipped with Portus version 2.1.

What are webhooks and how do they work?

Simply put, a webhook is a user-defined HTTP callback which notifies a specified endpoint about some sort of change. In Portus, this change can be either a push or delete event, i.e. webhooks will be triggered when you push or delete an image.

Creating a webhook in Portus is as simple as defining a URL. Although every HTTP request also requires a request method, this does not explicitly need to be set by the user, and defaults to GET in Portus. Another option, or better header, which has a default value is content-type. It defaults to application/json but can be changed if needed. Other customizable options include username and password, and custom HTTP headers. Per default, these are left empty if not explicitly specified. Furthermore, each webhook can be temporary disabled if it’s not needed, and be enabled again any time.

The way it works is that every push or delete event to the registry returns an event back to Portus itself. Portus only enriches these hooks with filtering at namespace level, authorization, persistence, and UI-based management. The latter includes enabling/disabling and retriggering webhooks, and customizing parameters regarding the endpoint. Should one want to filter at repository level, this has to be done by parsing the response.

Why use webhooks?

Since webhooks are triggered on events, they can be used for things like automatic deployment or triggering CI builds.

Simple example:

Your web application is containerized, and you have just pushed a new version of the used image to your registry. Since you want everything to work without much interaction, you have created a webhook which will notify some service. When this service gets notified, it can pull the new image and then restart the containerized web application. It’s as simple as that.

What information is provided in the request body?

The provided information is documented here. As mentioned above, we simply forward the received webhook content coming from the registry.

If you’re interested in how it works in detail, be sure to check out the code on GitHub.

Enjoy!