Webhook Security

In order for webhooks to work appropriately, the /flexdeploy/webhooks/v1 resource needs to be available for the system sending the webhook. This often means the endpoint needs to be publicly available which poses its own problems and security concerns which this document aims to address.

Warning

Before configuring any security or tunneling for webhooks, your security team should be engaged and approve the process.

Allowing webhooks into your FlexDeploy application

The easiest way to accomplish this is by using what is known as a 'reverse proxy'. A reverse proxy is the same as a normal proxy except it intercepts inbound traffic and routes to your application, whereas a normal proxy intercepts outbound traffic. Typically, the reverse proxy would be what is exposed to the public and it simply forwards the request to your FlexDeploy application.

Nginx has a nice article covering reverse proxies. One of the more simple reverse proxies you can use is ngrok, which also has a free tier. To get started quickly, simply download and copy ngrok to your FlexDeploy server and run the following command:

ngrok http 8000

Replace 8000 with whatever port your FlexDeploy application is running on. Ngrok will output http and https urls which are the urls you will use for your webhooks. For example, if you had a FlexDeploy webhook listening on /flexdeploy/webhooks/v1/git/push, then your full webhook url would be:

https://abc123.ngrok.io/flexdeploy/webhooks/v1/git/push

Caution

The approach outlined above is only intended to demonstrate the process and how to get up and running. What the above approach results in is opening port 8000 of the machine publicly, meaning anyone can access your FlexDeploy application by navigating to https://abc123.ngrok.io/flexdeploy. See the security concerns section below for ways to address this.

Securing your webhooks and application

Once we have some reverse proxy forwarding our webhooks to FlexDeploy, we need to ensure that no malicious requests are being forwarded from the reverse proxy. This can be accomplished a number of different ways as highlighted below:

Method	Description	Pros	Cons
IP Whitelisting	Denies any request from an IP address that is not included in the IP whitelist.	Arguably the most secure	In today's cloud and serverless world, the amount of IP addresses and ranges can be endless. For example, Slack webhooks originate from AWS which has 1000s of possible IP addresses.
Tokens	Passing some token (generally as a query param) in webhook urls. The reverse proxy then denies any request without this token.	Not restricted by IP	Token is visible in webhook urls
Resource Matching	Ensuring that your reverse proxy only forwards requests for certain resources. For example /flexdeploy/webhooks/v1. This denies any request to the base flexdeploy application through the proxy but allows requests to the webhook resource.	Not restricted by IP Not maintaining a token	Allows all requests through the proxy as long as the resource is /flexdeploy/webhooks/v1 Puts more ownership on the Provider Match script to determine malicious intent.
Hmac Encryption	A number of webhook providers (GitHub, Slack, Bitbucket Server) will encrypt the payload with a secret that you provide and pass the encrypted string as a header. When receiving the request you then encrypt the payload with the same secret and validate it matches the header that was passed from the provider. This is a more secure version of the Token approach above but not offered by all providers.	Second most secure behind IP whitelisting	Not offered by all providers

The approach used is ultimately decided by you. Having said that, if the dynamic IPs are not an issue for your team, then IP whitelisting should definitely be included. Experiment with any combination of the above and see what works for your organization.