Publishing events into an ASP.NET Core webhook with Octopus

I recently worked on a project that required listening to and acting on the events from our deployment software. We use Octopus for deploying our applications. One of the really useful features of Octopus is its ability to create subscriptions.

Subscriptions allow you to subscribe to events that are happening within Octopus, so you can be notified when events have occurred and react accordingly. So for example, you can create a subscription to be notified when a deployment is queued, starts, fails, completes etc. You may bind these subscription notifications into your Slack channel or other communication platform.

Our requirement was to create a custom Octopus subscription webhook using ASP.NET Core, and to send the results of the subscriptions back to our internal Customer Relationship Management (CRM) system. This would allow internal staff to view the status of a deployment without having to require access to Octopus.

The first step was therefore to create the subscription itself in Octopus. This article describes how to setup and configure a subscription within Octopus, so I won’t cover that here (the linked article does an excellent job of that).

Below shows a screenshot of the page for configuring subscriptions within Octopus.

Octopus sends a lot of very useful information. This is sent as a JSON payload via an HTTP POST method.

To inspect the contents and structure of the JSON payload that Octopus sends, you can create a very simple webhook using an excellent online tool called RequestBin. This is really useful when first creating your Octopus subscription, as you can inspect the JSON payload immediately and without having to write any code.

The Octopus subscription payload

Once we were satisfied we could use the contents of the JSON payload to meet the requirements of our application, we firstly mapped the JSON payload into a concrete POCO class as follows.

As can be seen, a lot of information is sent with the JSON payload.

The Filter class contains the filters you configured with your subscription. Within Octopus, there are a huge number of ways for you to configure your subscription. Without any filters, you will literally receive a payload for absolutely every event triggered within Octopus. It it highly unlikely this is what you want.

Another useful class is the Event class. Of particular interest is the property called RelatedDocumentIds.

This is a list of the document IDs that are associated with your deployment. It contains such IDs including

  • Deployment ID
  • Tenant ID
  • Space ID
  • Environment ID
  • Release ID
  • Project ID

Our process saves all these IDs into a SQL table when initially creating the deployment in Octopus (all completely automated via the Octopus API). Our webhook then extracts these values from the subscription JSON payload. The important ID is the Deployment ID. This is how you uniquely identify a deployment and associate it with the subscription notifications received via your webhook.

Adding filters to your Octopus subscription

The screenshot below shows the filters that are available to you to help you narrow your subscription to only those events you are interested in. I would recommend leaving some filters deliberately empty while you configure your subscription (to capture more events) to help you understand what information is being returned, and when. When you are confident you understand this, you can apply more filters so that you are only capturing the events you care about.

Creating the webhook to receive the Octopus subscription

We then created an ASP.NET Core controller to receive the JSON payload. This would be our webhook. With each JSON payload received via the webhook, we would exract the various related document IDs previously described.

Here is a very simple example of a webhook capable to receiving an Octopus subscription. Please note that for clarity I have removed validation, logging, security etc.

N.B. the above code will require you to install the Newtonsoft nuget package

Simple authentication / validation

It is worth noting that it is possible to implement simple authentication on your webhook. You can configure a header key and value that is sent to your webhook with each payload. This can be an encrypted string, a token, an API key or other means of authentication. You can pass it in as a key/value pair as you would in the header of a web request. Your webhook code then validates this and will accept/deny the webhook payload.


As you can see, it is relatively straight forward to create a subscription in Octopus and have a custom webhook writtten in ASP.NET Core process the events that are triggered by it. Your webhook can perform whatever actions you need. In our case, we updated our CRM to give visibility of deployments to non-technical users. However, you can process the Octopus subscription in whatever way you want.

I hope this article has given you some ideas on how you can use this powerful and useful feature of Octopus in your own organisation.

A father, cyclist, vegetarian, atheist, geek and multiple award winning technical author. Loves real ale, fine wine and good music. All round decent chap.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store