Incoming Webhooks

A webhook is a custom callback over HTTP(S) used to setup communication between applications. They provide a way to automatically notify other applications when an event has occurred in your application in the form of an HTTPS post payload. This eliminates the need to poll your external application to check for new events – the application will notify FlexDeploy when an event happens. Webhooks in FlexDeploy can be used to trigger actions in FlexDeploy based on events happening in other applications, thus eliminating some manual actions. For example, you can setup a webhook to build a project immediately after a push occurs in your SCM. This is just one example, and FlexDeploy's model offers flexibility in what you can accomplish with webhooks.

Getting Started

Checkout this Getting Started guide after you read this page.

Incoming Webhook Flow

There are two key aspects to webhooks in FlexDeploy; Providers and Functions. The flow diagram below illustrates how these different pieces interact with each other for a given webhook message:

In the above example we have an inbound webhook message from GitHub for the uri /flexdeploy/webhooks/v2/git/push.

When the message is received in FlexDeploy it will first sequentially evaluate the Provider Match Scripts until a Provider returns true. In the example above:
1. Evaluate Jira - In this case it returns false.
2. Evaluate GitHub - In this case it returns true.
3. Slack is never evaluated because GitHub has a higher priority and returned true.

Provider Ordering

You can improve performance by ordering your Provider Scripts in such a way that your most frequent messages match the first Provider.

After a Provider has matched, FlexDeploy will find all available Functions for that Provider that match the received URI. In this case the URI was git/push. We can see that of our 6 functions, 2 matched our GitHub provider with the git/push uri. Notice the "Jira - git/push" and "GitHub - stream/create" Functions did not match because both Provider and URI need to match.

The matched Functions will be executed in an indeterminate order. If you need Functions to execute in a specific order then it is recommended to combine the functionality into a single Function script.

Function URIs

The URIs after the base '/flexdeploy/webhooks/v2' uri are purely by convention and any uri can be used. In this example we had "git/push" but "something/random" would have worked exactly the same. The benefit of this approach is that you can direct 90% of your Git Repositories to a standard 'git/push' function while maybe the remaining 10% have more complex logic and need to be directed to a separate "git/complex" function.

Also note that query parameters can be passed and accessed from the scripts but are not included in the URI matching. I.E. git/push?projectId=123 will still match to git/push.

Navigation

Webhooks can be accessed from the menu at Administration → Incoming Webhooks. This page will show all received Webhook Messages, with options to view their details or resubmit them. Webhook Providers and Webhook Functions can be access in FlexDeploy from the Configuration button in the top right of the messages page.

Processing

Webhooks are processed asynchronously. This means that the service will return a 202 Accepted message before attempting to run the functions that you have written, this can be modified. To have a webhook process Synchronously, and return a 200, 404, or 500 depending on what happens while executing it, send in the Header "flex-sync-webhook" with a value of "true".

If processing synchronously, a 404 is returned if no function matches and is executed. A 200 will be returned if there is no error while processing any matching functions. A 500 will be returned if any function throws an error.

FlexDeploy 8.0