Cut a delivery door · Level 2

Behind, or starting here? Download the code as it should be before this lesson.

This lesson is optional. Some menus come from other systems, such as a planning tool, not from a person at the desk. A web trigger gives the app a URL they can call. Anyone who has the URL can call it, so the door only opens for requests that carry a secret code.

A web trigger

Another system calls the web trigger URL with the shared secret.

In the kitchen: Someone knocks at the delivery door with the code.

Runs in the Atlassian cloud · Back of house

Web trigger The delivery door

A webtrigger module gives your app a URL that outside systems can call over HTTPS.

A door at the back where other systems can drop off a menu without coming through the front.

Where the course explains it

Select any box in the diagram to see what it is.

Step 1: Make a door code and lock it in the safe

Runs in the Atlassian cloud · Back of house

Shared secret · the door code

A shared secret is a value only the app and the caller know. The caller sends it in a header; the app compares it with an encrypted variable before it does anything else. Compare in constant time, so how long the check takes reveals nothing, and never write the secret to the log.

In the kitchen The delivery door only opens for someone who knows the code, and the code lives in the safe.

Make a long random code on your laptop, then put it in the safe. The CLI asks for the value and hides it:

RunTerminal

openssl rand -hex 32
forge variables set --encrypt DOOR_CODE

Keep the code where the calling system can use it, never in its source code.

Stuck? I set or changed a variable

Done: forge variables list shows DOOR_CODE as encrypted

Step 2: Only open for the door code

Runs in the Atlassian cloud · Back of house

Web trigger · the delivery door

A webtrigger module gives the app a URL on Atlassian’s domain that outside systems can call over HTTPS. The function gets the request’s method, headers and body, and returns a status code, headers and a body. The URL works without any Atlassian login, which is why the function must check who is calling.

In the kitchen A door at the back where other systems can drop off a menu without coming through the front.

A new file checks the code first, then the menu, then accepts it exactly as the desk does: a jar, a slip on the rail, and a receipt.

New filesrc/door.js

A new file: check the code, check the menu, then accept it like the desk does.

1	+	Added: `import { timingSafeEqual } from 'node:crypto';`
2	+	Added: `import { acceptMenu } from './menus';`
3	+	Added: `import { validateMenu } from './lib/validate';`
4	+	Added:
5	+	Added: `const reply = (statusCode, body) => ({`
6	+	Added: `statusCode,`
7	+	Added: `headers: { 'Content-Type': ['application/json'] },`
8	+	Added: `body: JSON.stringify(body),`
9	+	Added: `});`
10	+	Added:
11	+	Added: `function header(request, name) {`
12	+	Added: `const key = Object.keys(request.headers ?? {}).find((k) => k.toLowerCase() === name);`
13	+	Added: `const value = key ? request.headers[key] : undefined;`
14	+	Added: `return Array.isArray(value) ? value[0] : value;`
15	+	Added: `}`
16	+	Added:
17	+	Added: `// Compare in constant time, so how long the answer takes gives nothing away.`
18	+	Added: `function sameSecret(given, expected) {`
19	+	Added: `const a = Buffer.from(String(given ?? ''));`
20	+	Added: `const b = Buffer.from(String(expected ?? ''));`
21	+	Added: `return a.length > 0 && a.length === b.length && timingSafeEqual(a, b);`
22	+	Added: `}`
23	+	Added:
24	+	Added: `/**`
25	+	Added: `* The delivery door: other systems can drop off a menu if they know the door code.`
26	+	Added: `* The URL is public, so check the code before anything else, and never log it.`
27	+	Added: `*/`
28	+	Added: `export async function run(request) {`
29	+	Added: `if (!sameSecret(header(request, 'x-door-code'), process.env.DOOR_CODE)) {`
30	+	Added: `console.warn('Delivery door: refused a request without the right code.');`
31	+	Added: `return reply(401, { error: 'Unauthorized' });`
32	+	Added: `}`
33	+	Added: `let payload;`
34	+	Added: `try {`
35	+	Added: `payload = JSON.parse(request.body ?? '');`
36	+	Added: `} catch {`
37	+	Added: `return reply(400, { error: 'Send the menu as JSON.' });`
38	+	Added: `}`
39	+	Added: `const check = validateMenu(payload);`
40	+	Added: `if (!check.ok) return reply(400, { error: check.error });`
41	+	Added: `const menuId = await acceptMenu({ ...check.menu, requestedBy: 'delivery-door' });`
42	+	Added: `return reply(202, { menuId });`
43	+	Added: `}`

Why: Web trigger · Shared secret · Environment variable

Stuck? I changed code in src/

Done: src/door.js exports run

Step 3: Cut the door into the licence

Another system calls the web trigger URL with the shared secret.Someone knocks at the delivery door with the code.

Editmanifest.ymlChange 1 of 2

A web trigger: a URL other systems can call.

85	85		`type: string`
86	86		`required: true`
87	87		`description: The research to publish, as plain text.`
	88	+	Added: `webtrigger:`
	89	+	Added: `- key: delivery-door`
	90	+	Added: `function: door`
	91	+	Added: `response:`
	92	+	Added: `type: dynamic`
88	93		`function:`
89	94		`- key: resolver`
90	95		`handler: index.handler`

Editmanifest.ymlChange 2 of 2

The function behind it.

101	106		`handler: rovo.researchDish`
102	107		`- key: publish-notes-fn`
103	108		`handler: rovo.publishNotes`
	109	+	Added: `- key: door`
	110	+	Added: `handler: door.run`
104	111		`resources:`
105	112		`- key: main`
106	113		`path: src/frontend/index.jsx`

Why: Web trigger

type: dynamic lets the function choose its own status code, such as 401 for a wrong code or 202 for an accepted menu.

Stuck? I changed manifest.yml

Done: manifest.yml has a delivery-door webtrigger and a door function

Step 4: Deploy and get the door’s address

RunTerminal

npm run build:ui
forge deploy
forge webtrigger create --functionKey delivery-door

Choose the Jira installation on your developer site. The CLI prints the URL. Treat it as private too: it is half of what a caller needs.

Stuck? Deploy stops after a permission change

Done: forge webtrigger create printed a URL

Step 5: Knock, with and without the code

Send a menu with the code. Replace the placeholders with your URL and code:

RunTerminal

curl -i -X POST '<your-web-trigger-url>' \
  -H 'Content-Type: application/json' \
  -H 'X-Door-Code: <your-door-code>' \
  -d '{"title": "Delivery menu", "notes": "Ana: add a green papaya salad. Ken: research a fish sauce supplier first.", "attendees": "Ana, Ken"}'

The answer is 202 with a menuId, and a few seconds later the dish tickets appear on the board, written by the prep cook as before. Send the same request without the X-Door-Code line: the answer is 401, and nothing is saved.

Stuck? My menu stays “waiting” or ends “failed”

Done: a call with the code got 202 and new tickets; a call without it got 401

Compare with yours: download the code after this lesson.