Page Comparison

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 routines 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 are the ones that are usually well understood: involve a well-understood process. In this scenario, the client initiates a connection and creates a request, . Power Scripts processes the request , it and returns a response in a straightforward manner.

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

The user and the Webhook

All the webhooks run unauthenticated, that is to say they use Webhooks in this system operate without authentication. In other words, they rely on the Jira addon pseudo-user, which is an internal to component of the cloud integration. In other words, you will still be able to perform certain operations, but not all of them.Functions/routines like currentUser(), archiveProject() still require an user to return the right result. If called from the 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 routines, 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 blow the script, yielding probably undesired results. The script will NOT have the required permissions to fully result in script errors and likely produce undesired outcomes. To ensure that the script has the necessary permissions to interact with Jira tickets, unless configured so or script explicitly calls out it is imperative to configure the permissions accordingly or explicitly specify the user to use be used within in the script using by utilizing the runAs routine.

Calling Webhooks

Webhooks are protected by tokens. A token is generated secured using tokens, which are unique for each HTTP method/verb you are using in calling the webhook so it will be valid for that method onlyemployed when making webhook calls, ensuring their validity for that specific method.

To generate the a token, you need to press should click on the lock icon, prompting the display of the following dialog will appear:

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

Expiring Tokens

By default, tokens have Tokens are assigned an expiration date and they cannot be used past beyond that date. You cannot manage tokens and invalidate them one by one since they are shown only once. You will need to treat them as secrets.If by mistake you shared inadvertently a token with another party, you may invalidate all tokens from a webhook 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 through a webhook modification. This can be accomplished by renaming the webhook and changing updating all references to it. We intend to make are committed to enhancing the ease of this process easier for you in the future.