Webhooks summary

Starting with version 4.5.0 we support Webhooks.

Webhooks gives the user the possibility to run existing SIL scripts, from outside of the Jira/Confluence instance, by using a REST/HTTP client, and retrieve the results of the script run.
In order for this to be possible, we need 2 things:

Create a SIL script.
Configure a webhook to run that SIL script.

Creating a SIL script

Almost any SIL script can be used, but the two Webhooks specific SIL routines getWebhookPayload and appendToWebhookResponse are the ones that make this feature powerful.

Example 1 - Getting the Webhooks payload from the calling client and returning custom results and HTTP response code:

//getting the REST/HTTP call input parameters:
WebhookPayload httpRequestPayload = getWebhookPayload();

//getting the used HTTP method:
string httpMethod = httpRequestPayload.httpMethod;//This can be something like "GET", "POST", "PUT" etc.

//getting the http request payload (body):
string httpPayload = httpRequestPayload.payload;

//getting the http query parameters:
WebhookParam[] httpQueryParams = httpRequestPayload.queryParams;
string firstQueryParamName = httpQueryParams[0].name;
string firstQueryParamValue = httpQueryParams[0].values[0];

//sending the response back to the caller:
appendToWebhookResponse("http method:");
appendToWebhookResponse(httpMethod);
appendToWebhookResponse("payload:");
appendToWebhookResponse(httpPayload);
appendToWebhookResponse("firstQueryParamName:");
appendToWebhookResponse(firstQueryParamName);
appendToWebhookResponse("firstQueryParamValue:");
appendToWebhookResponse(firstQueryParamValue);

//returning a custom HTTP status code:
return true, 1234;

The format for the return line, if used, should be return <true|false>[, <Custom HTTP status code>];
The first argument can only have the values true or false. True means that the script run was correctly, and false means that the script encountered a problem when it was run.

Webhooks Configuration

To define what URI and HTTP method(s) will be used to invoke a specific SIL script, the SIL Webhooks Configuration should be used. The page is located under Add-ons -> CPRIME PLUGINS CONFIGURATION.

To create a Webhook entry, click the "Add webhook" button.

A screen like the following will appear:

Fill the form with the desired paramenters:

Name - the name of the webhook. This will be used as an identificator for the webhook configuration.
Methods - the HTTP method (or methods) to bind the webhook to.
Scrip - the SIL Script that will run when calling this webhook.
Synchronized - the sync/async configuration for the webhook.

NOTE

The difference between synchronous and asynchronous is that the asynchronous Webhook SIL call can't return any results or custom HTTP codes to the caller.

This happens because the SIL script run task is added to a list of future tasks to be run, and the HTTP call ends.

With the synchronous option, the call will block until the SIL script run is completed, and the results will be returned to the caller.

After saving the configuration, a new entry like the following one will show up:

The URI column in the table will help you run your newly created wekbook. For example if your Jira installation instance is located at http://localhost, you can run the webhook using the address http://localhost/rest/keplerrominfo/refapp/latest/webhooks/mysilwebhook/run , with the selected HTTP method(s).

The webhook configured in the example image can be accessed using the HTTP methods GET and POST.

Changes are visible immediately and the webhook is immediately.

If you configured the the Webhook to be available for the GET HTTP method, you can test the webhook in the browser, giving it custom query parameters, and the result could look something like this (the above SIL script was used):

Webhooks Authentication

Fore the REST/HTTP client to be able to make any Webhooks calls, it needs to be authenticated into the Jira/Confluence instance.

Please see the official Atlassian Security pages:

Webhooks configuration

Webhooks summary

Creating a SIL script

Example 1 - Getting the Webhooks payload from the calling client and returning custom results and HTTP response code:

Webhooks Configuration

Webhooks Authentication

See also