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.
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 todays cloud and serverless world the amount of IP addresses and ranges can be endless. |
Viewing Messages
The table on the left side of the screen shows all webhooks received within the last week. Messages are purged automatically after 7 days.
| Field | Description |
|---|---|
| Message Id | The id given to message |
| Provider Name | The provider the message was matched to |
| Status | The status of the message. Can be SUCCESS, PENDING, or FAILED |
| Uri | The uri where the webhook was received |
| Message | A message containing more detail on the execution. This message can be set in a function script by using the LOG.setMessage function. If any errors occur during execution, the message will be overwritten |
| Created By | User who created the webhook |
| Created On | Date and time of webhook message creation |
Viewing Message Details
Click on any webhook message row in the table to view more details about an individual message. This will show more detail about the execution, including any webhook functions which were executed from this trigger and their statuses, as well as more context about the incoming webhook, including query parameters, headers, and additional properties. More information on the execution can be viewed by clicking . This will show any log messages printed in function scripts using the LOG methods. Click
to view the entire JSON POST payload as received from the provider. You can also submit an incoming webhook message for execution again with the
button. Keep in mind this is only meant to be used for debugging purposes.
Log Messages
Some logs are printed automatically during execution, but most are printed by using the LOG (link??) methods in the provider match and function scripts. By default, the logging level will be based on the global FlexDeploy logging level. This can be modified specifically for webhook logs by setting the logging level for flexagon.fd.services.webhooks.functions.LogFunctions in Admin → Admin Operations.