Skip to main content

Web trigger request and response

This page lists what a web trigger script receives, what it must return, and the responses Script Master sends without running the script.

Applies to: Script Master for Jira and Script Master for Confluence Β· Cloud

Globals​

The script is the body of an async function and runs on the Forge back end, as the app. These names are ready to use, with no import:

NameWhat it is
requestThe incoming HTTP request. See The request.
apiThe Forge API. Call Jira with api.asApp().requestJira() and Confluence with api.asApp().requestConfluence().
routeThe tag for REST paths, for example route`/rest/api/3/issue/${key}`. It encodes the values you insert.
fetchCalls to other systems.
authorizeThe Forge authorization helpers.
consoleLines you print with log, info, warn or error appear in tests and in the call's details in History.

The Forge API for server-side scripts page covers api, route and authorize.

The request​

FieldTypeDescription
methodStringThe HTTP method, for example GET or POST.
headersObject of string arraysThe request headers. Names are lowercase, and each value is an array: request.headers['authorization']?.[0].
bodyStringThe raw body. Parse JSON yourself with JSON.parse(request.body).
pathStringThe part of the URL path after the web trigger's base URL.
queryParametersObject of string arraysThe query parameters, each an array: request.queryParameters['space']?.[0]. It always holds id, the web trigger's ID.
contextObjectcloudId, the ID of your site, and moduleKey.

The response​

The script must return an object with a statusCode. Script Master sends it to the caller as the HTTP response.

FieldRequiredDescription
statusCodeYesThe HTTP status, for example 200 or 400. Use codes in the 2xx range for success.
statusTextNoThe status text, for example OK.
bodyNoThe response body, as a string. Turn objects into text with JSON.stringify().
headersNoResponse headers, each value an array: { 'Content-Type': ['application/json'] }.
if (!request.body) {
return { statusCode: 400, statusText: 'Bad Request' };
}

const data = JSON.parse(request.body);
return {
statusCode: 200,
headers: { 'Content-Type': ['application/json'] },
body: JSON.stringify({ received: data.key }),
};

Responses Script Master sends itself​

In these cases the caller gets Script Master's own response, not one from your script. Each has a JSON body with the same statusCode and statusText, for example {"statusCode":403,"statusText":"..."}.

StatusstatusTextWhen
400Web Trigger "id" is not providedThe URL has no id parameter.
403Web Trigger "<web-trigger-id>" cannot be executed, because it is disabledThe web trigger is switched off. The script doesn't run.
404Web Trigger is not found by "id"No web trigger has this ID, for example because it was deleted.
429Too Many Requests. You're doing that too often! Try again later.Calls arrive too fast. The script doesn't run.
500Internal Server Error. The web trigger script failed.The script threw an error, or the Companion App couldn't run it.
500The web trigger with "<web-trigger-id>" returned results without the required "statusCode" property. Please check the documentation for the expected return value.The script returned nothing, or an object without statusCode.
503Service Unavailable. The current version of the app is outdated. Please update to the latest version to continue using this feature.Script Master on your site needs an update.
PlaceholderDescription
<web-trigger-id>The ID from the id parameter of the URL.

When the script throws, the caller learns only that the script failed. The error message stays in the web trigger's History, so the caller never sees details of your script. Open the call there to read the error and the output lines. See Failures.