Jira webhooks

Jira webhooks are HTTP POST callbacks that Jira sends to your URL when issues, comments, sprints, versions and other items change.

61 events covered

These pages cover the events Jira sends from admin and app webhooks. Jira Automation is a separate feature: a rule calls out with its Send web request action and takes calls in with its incoming webhook trigger.

How Jira webhooks work

Webhooks save you polling the REST API for changes, and they come in two families. Admin webhooks are created in Jira administration or with /rest/webhooks/1.0/webhook. App webhooks belong to a Connect or OAuth 2.0 app, declared in a Connect descriptor or registered with /rest/api/3/webhook. Data Center documents only the admin console and REST API routes, and its behaviour differs from Cloud's in several places.

Each delivery is a JSON POST. webhookEvent in the body names the event, such as jira:issue_updated, and timestamp gives the time in epoch milliseconds. The rest depends on the event: issue events carry issue, user and issue_event_type_name, and only jira:issue_updated has a changelog listing the changed fields. Jira's webhook docs name no version header or field for payloads.

Key facts

Signature header
X-Hub-Signature

Not every delivery is signed: check your setup.

Scheme
HMAC-SHA256
Signed material
{raw body}

The request body as you received it. Atlassian says the HMAC uses the payload contents and the payload should be handled as UTF-8, and it mixes in no timestamp or nonce.

How events are identified
webhookEvent field in the body
Body format
JSON

Content type: application/json.

Other headers
x-atlassian-webhook-identifier, x-atlassian-webhook-retry, x-atlassian-webhook-flow
Envelope
timestamp, webhookEvent, issue_event_type_name, user, issue, changelog
Agent skill
npx skills add hookdeck/webhook-skills --skill jira-webhooks

Verify Jira webhooks →

Setting up Jira webhooks

  • On Jira Cloud, go to Settings, then System, then WebHooks under Advanced, which needs the Administer Jira global permission. Set a URL, a secret, your events and an optional JQL filter. POST /rest/webhooks/1.0/webhook does the same.
  • Apps declare a webhook module in a Connect descriptor or call POST /rest/api/3/webhook. Webhooks registered that way cover a subset of events and expire after 30 days unless you call Extend webhook life.
  • On Data Center, go to Administration, then System, then WebHooks. From Jira 10.x the REST resource moves to /rest/jira-webhook/1.0/webhooks.
  • Jira Cloud needs an HTTPS URL with a certificate from a globally trusted authority, so test locally through a tunnel such as npx hookdeck-cli listen 3000 jira --path /webhooks/jira. Atlassian's docs describe no way to resend a delivery.

Delivery behaviour

  1. Long outages cut retries

    If your endpoint gives no successful response for 30 minutes, Jira Cloud tries each webhook only once until a delivery succeeds. Reconcile against the REST API after an outage.

    Retries and outages →
  2. Retries repeat events

    Jira Cloud can deliver a webhook more than once if an acknowledgment fails. X-Atlassian-Webhook-Identifier stays the same across retries, so record it and skip repeats.

    Handle duplicates →
  3. Bulk operations cause spikes

    Bulk and cascade operations send their dependent webhooks on the Secondary flow, with a default limit of 10 concurrent requests per tenant and URL host. Respond quickly and queue the work, because errors can use up Jira's retries.

    Handle slow handlers →
  4. App webhooks expire

    Webhooks registered with /rest/api/3/webhook expire after 30 days and stop delivering. Call Extend webhook life on a schedule to keep them active.

    Other limits →

Jira webhook best practices

Common Jira webhook events

Issues

jira:issue_created An issue is created
jira:issue_updated An issue is edited or transitioned
jira:issue_deleted An issue is deleted

Comments and worklogs

comment_created A comment is added to an issue
comment_updated A comment is edited
worklog_created A worklog is logged on an issue

Sprints and releases

sprint_started A sprint begins
sprint_closed A sprint is completed
jira:version_released A project version is marked released

Events by resource

Resource Events Payloads
issue

jira:issue_created · jira:issue_updated · jira:issue_deleted · _property_set +8

12 1
project

project_created · _updated · _deleted · _soft_deleted +5

9 0
settings

option_voting_changed · option_watching_changed · option_unassigned_issues_changed · option_subtasks_changed +3

7 0
version

jira:version_released · jira:version_unreleased · jira:version_created · jira:version_moved +3

7 0
app

app_access_to_objects_blocked · _access_to_objects_in_container_blocked · jira_expression_evaluation_failed · connect_addon_enabled +1

5 0
sprint

sprint_created · _deleted · _updated · _started +1

5 0
board

board_created · _updated · _deleted · _configuration_changed

4 0
comment

comment_created · _updated · _deleted

3 0
filter

filter_created · _updated · _deleted

3 0
user

user_created · _updated · _deleted

3 0

1 more resource. All 61 events →

In this hub

Webhook events → Every covered Jira event, with payloads where the registry has them.
MCP events → How an agent subscribes to Jira events as MCP events.
Verify signatures → Signature facts, verification code and common failures.
Production guide → Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
Agent skill → Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill jira-webhooks

Stop losing Jira events when retries run out.

Jira Cloud gives up after five retries, and its docs describe no resend. Hookdeck Event Gateway accepts every Jira delivery, verifies the signature on signed admin webhooks, queues events and retries to your service on your schedule.

Not affiliated with Jira. Facts are compiled from public sources and linked inline.