Test Jira Cloud webhooks locally

Receive Jira Cloud events on your laptop while you build, with a URL Jira can reach.

Horizon has no Jira integration. Jira sends webhooks to a public URL, and Horizon provides that URL.

This guide covers admin webhooks, which you register in Jira Administration or with the REST API.

Before you beginCopy Anchor Link

• Node.js 18 or later
• A Horizon account and the CLI (see Getting started)
• A reserved subdomain for -s. Reserve one on the Subdomains page.
• A Next.js app that uses the App Router and runs on port 3000
• A Jira Cloud site, and a user with the Administer Jira global permission

import { createHmac, timingSafeEqual } from "node:crypto";

export async function POST(request: Request) {
  const secret = process.env.JIRA_WEBHOOK_SECRET;
  if (!secret) {
    return new Response("Missing JIRA_WEBHOOK_SECRET", { status: 500 });
  }

  const body = await request.text();
  const received = request.headers.get("x-hub-signature") ?? "";
  const expected = `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;

  const receivedBuffer = Buffer.from(received);
  const expectedBuffer = Buffer.from(expected);
  const isValid =
    receivedBuffer.length === expectedBuffer.length &&
    timingSafeEqual(receivedBuffer, expectedBuffer);

  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const payload = JSON.parse(body);
  console.log(`Received Jira event: ${payload.webhookEvent}`);

  return new Response("ok", { status: 200 });
}

JIRA_WEBHOOK_SECRET=replace-with-a-long-random-string

npm run dev

hrzn tunnel http://localhost:3000 -s my-jira-app

HORIZON: Tunnel connected
  URL          https://my-jira-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-jira-app

Check it worksCopy Anchor Link

In the terminal that runs hrzn, you see one line for the delivery:

  POST    200  /api/webhooks/jira

Your app terminal prints a line such as:

Received Jira event: jira:issue_updated

If the line shows [401], see Troubleshooting.

TroubleshootingCopy Anchor Link

The signature doesn't matchCopy Anchor Link

• Check that JIRA_WEBHOOK_SECRET is identical to the secret on the webhook, with no extra spaces or newline.
• Compute the HMAC over the raw body. Don't run JSON.parse and JSON.stringify first, because that can change the bytes.
• Check the method in the header. The handler accepts sha256 only.
• Restart npm run dev after you edit .env.local.

Jira sends the same event againCopy Anchor Link

Jira retries up to five times, with a random delay of 5 to 15 minutes between attempts. It retries on a connection failure and on status 408, 409, 425, 429 and 5xx. Use the X-Atlassian-Webhook-Identifier header, which stays the same across retries, to spot duplicates. X-Atlassian-Webhook-Retry holds the retry count.

The URL changed after a restartCopy Anchor Link

You started the tunnel without -s, so Horizon gave you a new random subdomain. Restart with -s my-jira-app and the URL stays the same. -s needs a subdomain you reserved, see Pricing.

Nothing reaches your appCopy Anchor Link

• Check that the Horizon terminal is still running. If its last line is Connection lost. Reconnecting…, wait for Reconnected.
• Check that the webhook URL ends with /api/webhooks/jira.
• Check that the webhook subscribes to the event you trigger.

Next stepsCopy Anchor Link

• Read Atlassian's Jira Cloud webhooks reference.