What we do
Tools
Industries
Department
How we workLet's talk →
Home/Jira/Jira Webhook Setup
Jira

Jira Webhook Setup: What Arrives, How Jira Retries, and How to Check It

A Jira webhook posts JSON to your URL when something happens, such as a work item created, updated or commented on, so your system never has to poll. Registering one takes two minutes. The receiving side is where the work is: Jira signs, retries and sometimes repeats deliveries, and your code has to handle all of it.

Create a Jira webhook

Where: you need the Administer Jira global permission.

Settings ⚙ System Advanced WebHooks

What to fill in: a name, the URL to call, the events (work item created, updated, deleted, comment added and so on), and an optional JQL filter such as project = OPS so only matching items send anything.

Set a secret. Jira then signs each delivery, and your receiver can prove it came from your site.

Not ready to use it? Disable it rather than delete it. Deleting removes it for good.

A system webhook or an automation web request?

Jira has two ways to push an event out. They behave differently when something goes wrong.

System webhook

Admin-registered, every matching event

  • Jira's own payload: the whole work item, plus a changelog on updates.
  • Signed with your secret, and retried up to five times on a timeout, a 429 or a 5xx.
  • Doesn't use automation steps.
  • Needs a Jira admin to create or change it.
Send web request

An action inside an automation rule

  • You write the body with smart values, and add your own headers.
  • The rule can wait for the reply and use it in later actions.
  • No retry queue: if your side is down, the run fails and the event is gone.
  • Each run counts against your automation step allowance.

Use a system webhook when missing an event costs you something, and a web request when you need conditions, a custom body or a reply in the same rule.

What a delivery contains

The headers matter as much as the body.

01

The body

  • webhookEvent, such as jira:issue_updated, and a timestamp.
  • issue_event_type_name and the user who made the change.
  • The issue object, shaped like the Get issue API response.
  • changelog with each field's old and new value, on updates only.
  • The comment object on comment events.
02

The headers

  • X-Hub-Signature: sha256= followed by the HMAC of the raw body with your secret.
  • X-Atlassian-Webhook-Identifier: the same on every retry of one event. Dedupe on it.
  • X-Atlassian-Webhook-Retry: how many retries this is.
  • X-Atlassian-Webhook-Flow: Primary for normal edits, Secondary for bulk changes.
03

URL and body options

  • Add variables to the URL, such as https://example.com/jira/{issue.key}.
  • Tick Exclude body if your receiver only needs the ping and reads the item from the Jira API.
  • Deliveries over 25 MB aren't sent at all.

Why a Jira webhook arrives twice, late, or not at all

Your receiver answers with something other than 200

How you'll know: Jira's failed-webhooks list shows deliveries you thought had worked.

Fix: Jira only treats a 200 as delivered. A 4xx such as 400 or 404 isn't retried at all, so that event is gone. Return 200 exactly, even if you queue the work for later.

Your receiver does the work before replying

How you'll know: Slow handling, then the same event a second time.

Fix: Jira retries on timeouts too. Reply 200 at once, then process. Use the identifier header so a retry that slips through is skipped.

A bulk edit arrives much later

How you'll know: Single edits arrive in seconds, but a bulk change of 300 items trickles in over several minutes.

Fix: Bulk and cascade changes go out as Secondary deliveries, which Jira aims to send within 15 minutes. Don't treat a gap as a failure.

Your service was down for an hour

How you'll know: Events stop arriving and some never come back.

Fix: Jira retries up to five times, then gives up. After 30 minutes of failures it makes only one attempt per event until one succeeds. Plan to catch up by searching Jira for items updated during the gap.

Nothing arrives at a plain HTTP address

How you'll know: The URL works from a browser, but Jira never calls it.

Fix: Port 80 isn't on Jira's allowed list. Serve the receiver over HTTPS.

An app's webhook stopped after a month

How you'll know: A webhook registered through the REST API by an app went quiet.

Fix: Those expire 30 days after creation unless the app refreshes them. Admin-created webhooks don't expire.

Before your receiver goes live

  • Does it check the signature against the raw body?

    Parsing the JSON first and re-serializing it changes the bytes, and the HMAC won't match.

  • Does it answer 200 within a second or two?

    A slow reply, a 429 or a 5xx earns you a retry. Most other codes get none, and the event is dropped.

  • Does it store the identifier header?

    That's the only reliable way to spot a repeat of the same event.

  • Does it cope with events out of order?

    Jira doesn't promise order. Compare the timestamp, or re-read the item, before overwriting newer data.

  • Does someone hear about it when it fails?

    Jira's side gives up quietly. Your receiver is the only place that can raise the alarm.

Questions people ask

Does Jira support webhooks?

Yes. Jira Cloud sends webhooks for work items, comments, worklogs, attachments, sprints, versions, projects and more, and you can narrow most work item events with a JQL filter.

How do I create a webhook in Jira?

As a Jira admin, open Settings, then System, then WebHooks under Advanced. Create one with a name, URL, the events you want, an optional JQL filter and a secret, then save.

What data does a Jira webhook send?

JSON with the event name, a timestamp, the user who made the change and the full work item. Update events add a changelog of old and new values, and comment events include the comment.

What is the difference between a Jira webhook and an automation rule?

A system webhook sends Jira's standard payload for every matching event, signs it and retries timeouts and server errors. An automation rule's send web request lets you build the payload, add conditions and read a reply, but it doesn't retry and it uses automation steps.

How do I verify a Jira webhook signature?

Compute an HMAC-SHA256 of the raw request body with your secret and compare it to the value after sha256= in the X-Hub-Signature header. Jira won't show the secret again after you save it, so store it somewhere safe.

Who builds the service that receives Jira webhooks?

Teams without a spare developer hand it to n-frames, which builds and hosts it: signature checks, instant replies, dedupe, catch-up after an outage, and the actual work in your other system, such as telling a customer their issue is resolved.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.