Webhooks

Webhooks make it possible to run existing SIL scripts from outside of the Jira / Confluence instance, by using a REST/HTTP client and retrieve the results of the run script.
In order for this to be possible, you need the following things:

1. Create a SIL script.

2. Configure a webhook to run that SIL script.

Creating a SIL Script

You can use almost any SIL script but the two Webhooks specific SIL functions getWebhookPayload and appendToWebhookResponse are especially powerful with this feature.

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 HTTP status code:
return 200;

The format for the return line is always return <HTTP status code>;
It is highly recommended that you use valid HTTP status codes.

Example 2 - Running code received from the client

//this may not be accepted by the security in your environment but it is possible!

WebhookPayload pload = getWebhookPayload(); //gets the payload

string codeToRun = pload.payload; //code is assumed to be in the payload

if(codeToRun == null) {
    logPrint("ERROR", "Nothing to run");
    return 400;
}
try {
    logPrint("INFO", "Executing remote code >>" + codeToRun);
    
    string [] args; //::TODO:: here you can create a protocol to transmit params. for simplicity, no params in this example
    
    string [] ret = runSILInline(codeToRun, args);
    
    logPrint("INFO", "Executing remote code done, results are >>" + ret);
    
    appendToWebhookResponse((string)ret);
    return 200;
} catch {
    appendToWebhookResponse("Exception:" + lastExceptionClass() + "///" + lastExceptionMessage());
    return 400; //we are not happy
}

Manage Webhooks Configuration

To define what URI and HTTP method(s) will be used to invoke a specific SIL™ script, use the SIL Webhooks configuration.

1. Log in to your Jira as Admin.

2. Go to your Administration > Add-ons > Power Apps Config → Integrations → Web Hooks.

3. To create a Webhook entry, click the the Add webhook button.
   A screen like the following will appear:
   

   

4. Fill in the parameters in the form:

   • Name - the name of the webhook. This will be used as an identifier for the webhook configuration.

   • Methods - the HTTP method (or methods) to bind the webhook to.

   • Script - SIL™ script that will run when calling this webhook.

   • Synchronized - the sync/async configuration for the webhook.

5. Save the configuration.
   After you save  the configuration, a new entry like the following one will show up:

   

6. The URI column in the table will help you run your newly created webhook. For example if your Power Scripts installation instance is located at https://us1.powerscripts.anova.appfire.app/ (this is the canonical name for US-based installations) you can run the webhook using the  https://us1.powerscripts.anova.appfire.app/rest/keplerrominfo/refapp/latest/webhooks/testsupport/run address with the selected HTTP method(s). See calling webhooks chapter below.

You can edit the webhook so it will conform to your ad-hoc protocol by pressing the edit icon, and delete the webhook pressing on the bin icon.

Synchronous vs Asynchronous Webhooks

Synchronous webhooks involve a well-understood process. In this scenario, the client initiates a connection and creates a request. Power Scripts processes the request and returns a response in a straightforward manner.

In contrast, asynchronous webhooks operate more like a "fire-and-forget" mechanism. When an asynchronous webhook is triggered, it immediately returns an HTTP code 200 response, but the actual processing is scheduled to occur in the background. This means that return codes are disregarded, and the response is entirely discarded. Importantly, the caller will not receive any further updates or feedback.

The user and the Webhook

Webhooks in this system operate without authentication. In other words, they rely on the Jira addon pseudo-user, which is an internal component of the cloud integration. However, it's important to note that while certain operations can still be performed using these webhooks, not all functionalities are accessible.

Specific functions and functions, such as currentUser() and archiveProject(), require a user context to provide the expected results. If these functions are invoked from an unauthenticated context, they will result in script errors and likely produce undesired outcomes. To ensure that the script has the necessary permissions to interact with Jira tickets, it is imperative to configure the permissions accordingly or explicitly specify the user to be used within the script by utilizing the runAs function.

Calling Webhooks

Webhooks are secured using tokens, which are unique for each HTTP method/verb employed when making webhook calls, ensuring their validity for that specific method.

To generate a token, you should click on the lock icon, prompting the display of the following dialog:

Edit the Expiration date and click on the method (in the above example, POST). The token will be generated, already encoded (so use it as it is). Copy the token, it will not be shown again. As stated in the above dialog, you will need to either:

1. Add a header named X-SIL-TOKEN containing this token; this is the preferred way, no trails in logs, or

2. Add a parameter in the query named siltoken or silToken containing the above value

With this, we can now call the webhook (via curl or any tool you choose):

https://<addon_base_url>/rest/keplerrominfo/refapp/latest/webhooks/<webhook-name>/run?silToken=<token> 

where:

1. <addon_base_url> is your server location (right now us1.powerscripts.anova.appfire.app)

2. <webhook-name> is the webhook name

3. <token> is the token above

Token Expiration

Tokens are assigned an expiration date by default, rendering them unusable beyond this specified date. It's important to note that individual token management and invalidation is not feasible, as tokens are single-use entities. Consequently, it is essential to treat tokens as confidential assets.

In the event of accidental token sharing with unintended parties, you have the option to invalidate all associated tokens.

The last operation in the webhook config page invalidates all the tokens, on all HTTP methods ever used. You will have to generate new tokens for the webhook to be invoked properly.