# Jira webhooks

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

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](https://support.atlassian.com/cloud-automation/docs/jira-automation-actions/) and takes calls in with its [incoming webhook trigger](https://support.atlassian.com/cloud-automation/docs/configure-the-incoming-webhook-trigger-in-atlassian-automation/).

Agent skill: `npx skills add hookdeck/webhook-skills --skill jira-webhooks` ([details](https://hookdeck.com/webhooks/jira/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Jira's official docs](https://developer.atlassian.com/cloud/jira/platform/webhooks/).

[Overview](https://hookdeck.com/webhooks/jira) · [Webhook events (61)](https://hookdeck.com/webhooks/jira/events) · [MCP events](https://hookdeck.com/webhooks/jira/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/jira/verify) · [Production guide](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/jira/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `X-Hub-Signature` Not every delivery is signed: check your setup. | [Jira docs](https://developer.atlassian.com/cloud/jira/platform/webhooks/#secure-admin-webhooks) |
| Scheme | `HMAC-SHA256` | [Jira docs](https://developer.atlassian.com/cloud/jira/platform/webhooks/#secure-admin-webhooks) |
| 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. | [Jira docs](https://developer.atlassian.com/cloud/jira/platform/webhooks/#secure-admin-webhooks) |
| How events are identified | `webhookEvent field in the body` | [Jira docs](https://developer.atlassian.com/cloud/jira/platform/webhooks/) |
| Body format | `JSON` Content type: application/json. | [Jira docs](https://developer.atlassian.com/cloud/jira/platform/webhooks/) |
| Other headers | `x-atlassian-webhook-identifier, x-atlassian-webhook-retry, x-atlassian-webhook-flow` | [Jira docs](https://developer.atlassian.com/cloud/jira/platform/webhooks/) |
| Envelope | `timestamp, webhookEvent, issue_event_type_name, user, issue, changelog` | [Jira docs](https://developer.atlassian.com/cloud/jira/platform/webhooks/) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill jira-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/jira/skill) |

[Verify Jira webhooks](https://hookdeck.com/webhooks/jira/verify)

## 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.

## 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

- **Timeout:** not published. Jira Cloud retries a delivery that times out, but states no limit. [Guide](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** up to 5 on Cloud. 5 to 15 minutes apart; Data Center documents no retry policy. [Guide](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries run out:** no documented resend. only Connect apps can list failures, for about 72 hours. [Guide](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts#retries)
- **Duplicates:** possible. X-Atlassian-Webhook-Identifier stays the same across retries. [Guide](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts#duplicates)

## Known failure modes

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](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts#retries)
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](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts#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](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts#timeouts)
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](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts#other-limits)

From [Hookdeck's Jira guide](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts).

## Jira webhook best practices

- **[Set a secret and verify every signature](https://hookdeck.com/webhooks/jira/verify).** An admin webhook with no secret is unsigned, so anyone who finds your URL can send fake events to it. On app webhooks, verify the JWT in `Authorization` instead.
- **[Respond quickly and queue the work](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts#timeouts).** Atlassian publishes no timeout for these webhooks, but it does say slow recipients hold up later deliveries and can use up their retries.
- **[Track X-Atlassian-Webhook-Identifier](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts#duplicates).** A retry has the same value as the original on Jira Cloud. It's unique within a tenant, so include the site in your key if you serve several.
- **[Return a status that says what you want](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts#retries).** Jira Cloud retries 408, 409, 425, 429 and 5xx. Any other failure, such as a 400 or 404, isn't retried.
- **[Keep JQL filters simple](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts#choosing-events).** The query runs with each event, and some custom fields take seconds. An empty query matches every issue in every project.
- **[Refresh app webhooks before they expire](https://hookdeck.com/webhooks/jira/guide-duplicates-ordering-retries-timeouts#other-limits).** Webhooks registered with `/rest/api/3/webhook` stop after 30 days. Run a job that calls Extend webhook life well before then.

## Common Jira webhook events

### Issues

- [jira:issue_created](https://hookdeck.com/webhooks/jira/events#jira%3Aissue_created): An issue is created
- [jira:issue_updated](https://hookdeck.com/webhooks/jira/events#jira%3Aissue_updated): An issue is edited or transitioned
- [jira:issue_deleted](https://hookdeck.com/webhooks/jira/events#jira%3Aissue_deleted): An issue is deleted

### Comments and worklogs

- [comment_created](https://hookdeck.com/webhooks/jira/events#comment_created): A comment is added to an issue
- [comment_updated](https://hookdeck.com/webhooks/jira/events#comment_updated): A comment is edited
- [worklog_created](https://hookdeck.com/webhooks/jira/events#worklog_created): A worklog is logged on an issue

### Sprints and releases

- [sprint_started](https://hookdeck.com/webhooks/jira/events#sprint_started): A sprint begins
- [sprint_closed](https://hookdeck.com/webhooks/jira/events#sprint_closed): A sprint is completed
- [jira:version_released](https://hookdeck.com/webhooks/jira/events#jira%3Aversion_released): A project version is marked released

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [issue](https://hookdeck.com/webhooks/jira/events#resource-issue) | 12 | 1 |
| [project](https://hookdeck.com/webhooks/jira/events#resource-project) | 9 | 0 |
| [settings](https://hookdeck.com/webhooks/jira/events#resource-settings) | 7 | 0 |
| [version](https://hookdeck.com/webhooks/jira/events#resource-version) | 7 | 0 |
| [app](https://hookdeck.com/webhooks/jira/events#resource-app) | 5 | 0 |
| [sprint](https://hookdeck.com/webhooks/jira/events#resource-sprint) | 5 | 0 |
| [board](https://hookdeck.com/webhooks/jira/events#resource-board) | 4 | 0 |
| [comment](https://hookdeck.com/webhooks/jira/events#resource-comment) | 3 | 0 |
| [filter](https://hookdeck.com/webhooks/jira/events#resource-filter) | 3 | 0 |
| [user](https://hookdeck.com/webhooks/jira/events#resource-user) | 3 | 0 |

1 more resource. [All 61 events](https://hookdeck.com/webhooks/jira/events)

## In this hub

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

Not affiliated with Jira. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/jira.json) · [Report a correction](https://hookdeck.com/contact)
