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 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
{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.
x-atlassian-webhook-identifier, x-atlassian-webhook-retry, x-atlassian-webhook-flow 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/webhookdoes 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
not published Jira Cloud retries a delivery that times out, but states no limit Retries up to 5 on Cloud 5 to 15 minutes apart; Data Center documents no retry policy After retries run out no documented resend only Connect apps can list failures, for about 72 hours Duplicates possible X-Atlassian-Webhook-Identifier stays the same across retries Known failure modes
From Hookdeck's Jira guide →-
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 → -
Retries repeat events
Jira Cloud can deliver a webhook more than once if an acknowledgment fails.
Handle duplicates →X-Atlassian-Webhook-Identifierstays the same across retries, so record it and skip repeats. -
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 → -
App webhooks expire
Webhooks registered with
Other limits →/rest/api/3/webhookexpire after 30 days and stop delivering. Call Extend webhook life on a schedule to keep them active.
Jira webhook best practices
- Set a secret and verify every signature.
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
Authorizationinstead. - Respond quickly and queue the work. 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. 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. 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. 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.
Webhooks registered with
/rest/api/3/webhookstop after 30 days. Run a job that calls Extend webhook life well before then.
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 | 12 | 1 |
project | 9 | 0 |
settings | 7 | 0 |
version | 7 | 0 |
app | 5 | 0 |
sprint | 5 | 0 |
board | 4 | 0 |
comment | 3 | 0 |
filter | 3 | 0 |
user | 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.