Вернуться к инструкциям
Инструкция

Как принимать вебхуки от Jira Cloud

Подключите Jira Cloud к локальному приложению через Adal CLI и проверьте подпись события создания задачи.

15 мин

Когда в тестовом проекте Jira Cloud создаётся задача, Jira отправляет событие jira:issue_created на HTTPS-адрес Сервера Adal Cloud. Adal CLI доставляет запрос в локальный обработчик. В примере обработчик проверяет подпись и выводит ключ задачи, например TEST-1.

Понадобятся глобальное разрешение Administer Jira, тестовый проект без рабочих данных, аккаунт Adal Cloud, Adal CLI и Node.js 24.

1. Запустите локальный обработчик

Создайте случайный секрет и сохраните его в менеджере паролей. Передайте его процессу через переменную окружения JIRA_WEBHOOK_SECRET. Это отдельный секрет для подписи Jira. Токен CLI понадобится для подключения к Каналу Adal.

Сохраните код в jira-webhook.mjs и запустите 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');

Пример принимает до 1 МиБ и поддерживает подпись sha256 в заголовке X-Hub-Signature. HMAC вычисляется по исходным байтам тела до разбора JSON. Повторная сериализация JSON может изменить байты и нарушить проверку подписи. Подпись административных вебхуков Jira

2. Подключите Adal CLI

  1. В Inbound → Servers создайте Сервер, который принимает POST, и скопируйте его HTTPS-адрес.

  2. В Inbound → Channels создайте CLI-Канал, добавьте включённый Ендпоинт http://127.0.0.1:3000 и сохраните его. Путь /webhooks/jira добавится при доставке входящего запроса.

  3. В Inbound → Routers свяжите Сервер и Канал включённым Маршрутизатором.

  4. Выпустите токен CLI для Канала и запустите ./adal-cli --token '<CLI_TOKEN>' или .\adal-cli.exe --token '<CLI_TOKEN>' в PowerShell. Оставьте клиент и обработчик запущенными. Подключение Adal CLI

3. Создайте вебхук в Jira Cloud

Откройте Settings → System, в разделе Advanced выберите WebHooks и создайте вебхук. Управление вебхуками в Jira

  • В поле URL укажите скопированный HTTPS-адрес Сервера с путём /webhooks/jira.

  • В поле Secret укажите значение JIRA_WEBHOOK_SECRET.

  • Выберите только событие создания задачи (jira:issue_created). Введите фильтр JQL project = TEST, подставив ключ своего тестового проекта.

  • Оставьте Exclude body выключенным, включите вебхук и сохраните его.

4. Проверьте приём и доставку

Создайте задачу в тестовом проекте. В Inbound → Requests найдите POST /webhooks/jira и проверьте, что в теле есть webhookEvent: jira:issue_created и ключ новой задачи. В Deliveries откройте попытку своего Канала и проверьте ответ обработчика 204. В терминале приложения должна появиться строка вроде Issue created: TEST-1.

Ответ Сервера Adal, например 202, подтверждает приём запроса от Jira. Результат вызова локального обработчика отображается в Deliveries.

  • Запроса нет в журнале. Проверьте HTTPS-адрес, состояние вебхука, выбранное событие и JQL. Создайте новую задачу после сохранения настроек.

  • Запрос принят, но обработчик не вызван. Проверьте Маршрутизатор, состояние Ендпоинта и подключение Adal CLI.

  • В попытке виден 401. Сверьте секреты и проверьте наличие X-Hub-Signature. Если вы обрабатываете запрос в своём приложении, проверяйте подпись до преобразования тела.

Пример только выводит ключ. Если обработчик записывает данные или запускает автоматизацию, учитывайте повторные доставки. Для дедупликации сохраняйте X-Atlassian-Webhook-Identifier вместе с идентификатором экземпляра Jira. Идентификатор вебхука уникален в пределах экземпляра и сохраняется при повторах Jira. После проверки отключите тестовый вебхук. Политика повторов Jira