Back to How To
How To

How to receive webhooks from Jira Cloud

Connect Jira Cloud to a local app through Adal CLI and verify the signature of an issue creation event.

15 min

When someone creates an issue in a test project, Jira Cloud sends a jira:issue_created event to your Adal Cloud Server's HTTPS URL. Adal CLI delivers the request to a local handler. The example verifies the signature and prints the issue key, such as TEST-1.

You need the Administer Jira global permission, a test project with sample data, an Adal Cloud account, Adal CLI, and Node.js 24.

1. Run the local handler

Generate a random secret and save it in your password manager. Set JIRA_WEBHOOK_SECRET in the handler's environment. Jira uses this secret to sign requests. The CLI token is a separate credential for connecting to an Adal Channel.

Save the code as jira-webhook.mjs and run node jira-webhook.mjs.

import { createHmac, timingSafeEqual } from 'node:crypto'; import { createServer } from 'node:http'; const secret = process.env.JIRA_WEBHOOK_SECRET; if (!secret) throw new Error('Set JIRA_WEBHOOK_SECRET'); createServer(async (req, res) => { if (req.method !== 'POST' || req.url !== '/webhooks/jira') { return res.writeHead(404).end(); } const signature = req.headers['x-hub-signature']; if (!/^sha256=[a-f0-9]{64}$/i.test(signature ?? '')) { return res.writeHead(401).end(); } const chunks = []; let size = 0; try { for await (const chunk of req.iterator({ destroyOnReturn: false })) { size += chunk.length; if (size > 1024 * 1024) { return res.writeHead(413, { Connection: 'close' }).end(); } chunks.push(chunk); } } catch { return res.writeHead(400).end(); } const body = Buffer.concat(chunks); const expected = createHmac('sha256', secret).update(body).digest(); const received = Buffer.from(signature.slice(7), 'hex'); if (!timingSafeEqual(expected, received)) { return res.writeHead(401).end(); } let event; try { event = JSON.parse(body.toString('utf8')); } catch { return res.writeHead(400).end(); } if (event?.webhookEvent === 'jira:issue_created' && typeof event.issue?.key === 'string') { console.log('Issue created:', event.issue.key); } res.writeHead(204).end(); }).listen(3000, '127.0.0.1');

The example accepts up to 1 MiB and supports the sha256 signature in the X-Hub-Signature header. It computes the HMAC over the original body bytes before parsing JSON. Serializing the JSON again can change those bytes and invalidate the signature. Jira admin webhook signatures

2. Connect Adal CLI

  1. In Inbound → Servers, create a Server that accepts POST and copy its HTTPS URL.

  2. In Inbound → Channels, create a CLI Channel, add an enabled Endpoint at http://127.0.0.1:3000, and save it. The path /webhooks/jira is appended when Adal delivers the incoming request.

  3. In Inbound → Routers, connect the Server and Channel with an enabled Router.

  4. Issue a CLI token for the Channel and run ./adal-cli --token '<CLI_TOKEN>' or .\adal-cli.exe --token '<CLI_TOKEN>' in PowerShell. Keep both the client and the handler running. Adal CLI setup

3. Create the Jira Cloud webhook

Go to Settings → System, select WebHooks under Advanced, and create a webhook. Manage webhooks in Jira

  • For URL, use the Server HTTPS URL you copied, followed by /webhooks/jira.

  • For Secret, enter the value of JIRA_WEBHOOK_SECRET.

  • Select the issue creation event (jira:issue_created) only. Set the JQL filter to project = TEST, substituting your test project's key.

  • Leave Exclude body unchecked, enable the webhook, and save it.

4. Verify intake and delivery

Create an issue in the test project. In Inbound → Requests, find POST /webhooks/jira and check that the body contains the jira:issue_created value for webhookEvent and the new issue key. Open the attempt for your Channel under Deliveries and check for a 204 response from the handler. The application terminal should print a line such as Issue created: TEST-1.

The Adal Server response, such as 202, confirms that Adal received the request from Jira. The local handler's result appears under Deliveries.

  • No request in the journal. Check the HTTPS URL, webhook status, selected event, and JQL. Create a new issue after saving any changes.

  • Adal received the request but the handler did not run. Check the Router, Endpoint status, and CLI connection.

  • The attempt shows 401. Check that both sides use the same secret and that the request includes X-Hub-Signature. If you use your own handler, verify the signature before transforming the body.

The example prints the key. If your handler writes data or triggers automation, account for duplicate deliveries. For deduplication, store X-Atlassian-Webhook-Identifier together with the Jira tenant identifier. The webhook identifier is unique within a tenant and stays the same across Jira retries. Disable the test webhook when you finish. Jira retry policy