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:
| Name | What it is |
|---|---|
request | The incoming HTTP request. See The request. |
api | The Forge API. Call Jira with api.asApp().requestJira() and Confluence with api.asApp().requestConfluence(). |
route | The tag for REST paths, for example route`/rest/api/3/issue/${key}`. It encodes the values you insert. |
fetch | Calls to other systems. |
authorize | The Forge authorization helpers. |
console | Lines 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β
| Field | Type | Description |
|---|---|---|
method | String | The HTTP method, for example GET or POST. |
headers | Object of string arrays | The request headers. Names are lowercase, and each value is an array: request.headers['authorization']?.[0]. |
body | String | The raw body. Parse JSON yourself with JSON.parse(request.body). |
path | String | The part of the URL path after the web trigger's base URL. |
queryParameters | Object of string arrays | The query parameters, each an array: request.queryParameters['space']?.[0]. It always holds id, the web trigger's ID. |
context | Object | cloudId, 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.
| Field | Required | Description |
|---|---|---|
statusCode | Yes | The HTTP status, for example 200 or 400. Use codes in the 2xx range for success. |
statusText | No | The status text, for example OK. |
body | No | The response body, as a string. Turn objects into text with JSON.stringify(). |
headers | No | Response 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":"..."}.
| Status | statusText | When |
|---|---|---|
400 | Web Trigger "id" is not provided | The URL has no id parameter. |
403 | Web Trigger "<web-trigger-id>" cannot be executed, because it is disabled | The web trigger is switched off. The script doesn't run. |
404 | Web Trigger is not found by "id" | No web trigger has this ID, for example because it was deleted. |
429 | Too Many Requests. You're doing that too often! Try again later. | Calls arrive too fast. The script doesn't run. |
500 | Internal Server Error. The web trigger script failed. | The script threw an error, or the Companion App couldn't run it. |
500 | The 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. |
503 | Service 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. |
| Placeholder | Description |
|---|---|
<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.
Relatedβ
- Test a web trigger: try a request and read the response before you save.
- Require a token on a web trigger: answer
401or403to unknown callers. - Web Triggers AI prompt: the same reference, written for an AI assistant.