Jira webhooks in production: duplicates, ordering, retries and timeouts
This guide covers the problems Jira webhooks cause in production and how to handle each one. What Jira sends and how it's signed is on the Jira webhooks overview, every event type is on Jira webhook events, and signature verification code is on Verify Jira webhooks.
Jira's behaviour depends on where a webhook lives. Most of this guide is about Jira Cloud, whose docs cover retries, delivery headers and concurrency. Where Data Center differs, the section says so, and its queue limits are in Other limits.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Return a 200 quickly and process in a background job; Jira publishes no limit | Accepts the delivery at once, then queues it for your service |
| Duplicates | Record X-Atlassian-Webhook-Identifier per site; make handlers idempotent | Drops repeats before they reach your handler |
| Ordering | Compare the body's timestamp; fetch current state when in doubt | Logs every event and attempt, so you can see arrival order when debugging |
| Retries | Return the right status, watch the retry header, reconcile after an outage | Accepts deliveries while your service is down and retries them |
| Choosing events | Subscribe by entity, keep JQL simple, know which events ignore filters | Filters and routes events by header or body |
| Testing | Use a public HTTPS URL with a trusted certificate and a test project | Sample payloads in Inspect, and forwarding and replay with the CLI |
| Other limits | Refresh app webhooks, plan for 25 MB and registration caps, update IP allowlists, tune Data Center queues | Fans one webhook out to many destinations at a rate you set |
Jira webhook timeouts and slow handlers
Return a 200 as quickly as you can, then do the work in a background job. Atlassian publishes no timeout for Jira platform webhooks, so don't build around a number.
Why it happens: Jira Cloud retries a delivery when the connection fails or times out, but doesn't say when that is. The 5-second connection and 20-second response limits belong to legacy Jira Service Management automation webhooks, a separate feature.
Jira also limits concurrency. It allows a default of 20 concurrent requests per tenant and URL host for Primary webhooks and 10 for Secondary ones, and says those limits can change without notice. All your webhooks on one host share them. Atlassian warns that consuming too slowly causes errors that can use up the retries, and so lose webhooks. Bulk changes and project or issue deletions cause the largest spikes.
Fix it in your handler:
- Verify the signature and return a
200straight away. - Push the event onto a queue and process it in a worker. See why to process webhooks asynchronously.
- Size the queue and workers for bulk operations.
X-Atlassian-Webhook-Flow: Secondarymarks webhooks that come from a bulk or cascade operation.
With Event Gateway: Hookdeck accepts each Jira delivery immediately, then queues events and delivers them to your service at a rate you set, with its own retries. A slow handler no longer fails a Jira delivery.
Duplicate Jira webhooks
Record each X-Atlassian-Webhook-Identifier value you process and skip repeats.
Why it happens: Jira Cloud says some webhooks might be delivered more than once if the delivery acknowledgment fails. The identifier stays the same across retries, and it's unique within a Jira Cloud tenant rather than globally.
A webhook used as a workflow post function can also fire twice: once for the event and once for the transition if it's also listening to events. Those are two deliveries of one change, so the identifier may not connect them.
Fix it in your handler:
- Store processed identifiers in a table with a unique constraint. If you serve several Jira sites, include the site in the key.
- Make every handler idempotent: the same result however many times it runs.
- On a post function webhook, unselect all events on the webhook, as Atlassian advises.
- On Data Center, whose docs don't mention the header, build a key from
webhookEvent,timestampand the entity's id, and check whether your version sends the header.
With Event Gateway: Hookdeck deduplicates events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.
Out-of-order Jira webhooks
Atlassian's docs make no promise about delivery order. Compare the body's timestamp when order matters.
Why it happens: A retry can land 5 to 15 minutes after the failure that caused it, well after newer events. Delivery targets differ too: Primary webhooks should arrive within 30 seconds and Secondary ones within 15 minutes. Deleting an issue sends the deletion as Primary and the dependent comment, attachment and issue link deletions as Secondary. For more on the general problem, see Webhook Ordering: Why It's Hard and How to Handle It.
Fix it in your handler:
- Compare
timestamp, in epoch milliseconds, before you apply an update, so an older event can't overwrite newer state. - On
jira:issue_updated, usechangelogto see which fields changed rather than copying the whole issue over your record. - When two events are too close to call, fetch the issue's current state from the REST API.
With Event Gateway: Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.
Jira webhook retries and outages
Jira Cloud retries a failed delivery up to five times, 5 to 15 minutes apart, and its docs describe no way to resend it after that. Return the right status, watch for retries and reconcile after any outage.
Why it happens: Under the retry policy, Jira retries on 408, 409, 425, 429 and 5xx responses and on connection failures or timeouts. Any other error, such as a 400 or 404, isn't retried.
If your endpoint doesn't respond successfully within 30 minutes, Jira tries each webhook just once until it records a success, so events that fail in that period get no retries at all.
When retries run out, Get failed webhooks returns the failures, including the body, but only to Connect apps, and a failure may be gone after 72 hours. Admin webhooks and OAuth 2.0 apps have no equivalent in the docs.
Fix it in your handler:
- Return a 5xx or 429 for a temporary failure you want retried, and use other 4xx codes only for requests you never want to see again.
- Log
X-Atlassian-Webhook-Retry. It carries the retry count, and a rising number warns you before retries run out. - In a Connect app, poll Get failed webhooks at least once every 72 hours and process what it returns.
- After an outage, run a job that searches the REST API for issues updated since your last event.
Data Center is different. Its docs describe no retry policy. After 5 consecutive failures, Jira treats a webhook as unhealthy and skips it for a delay that starts at 10 seconds and grows to 2 hours by default, until a dispatch succeeds. Jira never disables a webhook automatically, so failures can go unnoticed. Check the logs with DEBUG on com.atlassian.webhooks, and reconcile as in step 4.
With Event Gateway: Hookdeck accepts deliveries while your service is down, then retries them on your schedule and lets you replay any event from its log. Your endpoint's outage doesn't reach Jira, so Jira keeps seeing successful responses.
Choosing which Jira events to listen to
Subscribe to the entities you need, filter with JQL where the event supports it, and ignore event types your code doesn't handle yet.
Why it matters: Atlassian suggests registering for all events of the relevant entity if you're unsure, so you won't need to change the webhook later. Filters have limits that are easy to miss:
- Cost. A JQL query runs with each event, and some custom fields can take seconds. On Data Center, matching runs synchronously, one filter at a time, on the thread that raised the event, which may be a user's request. Atlassian's example is 20 webhooks at 200 ms each, which adds 4 seconds.
- An empty query. It matches all issues in all projects, and Atlassian warns the webhooks may reveal sensitive information.
- Events that ignore filters. Sprint and version events ignore JQL, field and property filters, so filter them in your handler.
- Webhooks registered with
/rest/api/3/webhook. They take a subset of events and JQL: clauses such asproject,statusandassignee, with only=,!=,INandNOT IN.
Some changes don't send the event you might expect. Project deletion doesn't send issue_deleted, attachments added in the create issue dialog don't send attachment_created, and a post function on the Create Issue transition doesn't fire. Atlassian's event list also says merging a version sends jira:version_deleted with a mergedTo property, while its app webhook lists name jira:version_merged. The full list, with sample payloads, is on Jira webhook events.
Fix it in your handler:
- Branch on
webhookEventand ignore names you don't recognise. - Use standard fields in JQL, such as
projectandissuetype, and test any custom field's speed first. - Handle both version merge names, and check for
mergedToon a deletion. - If deleting a project matters to you, handle
project_deletedand clean up its issues yourself.
With Event Gateway: Register one Jira webhook with a light filter, then let Hookdeck filter and route events by type or any other property, so one Jira URL can feed several services.
Testing and debugging Jira webhooks locally
Test through a public HTTPS URL with a trusted certificate, against a dedicated project.
Why it happens: Jira Cloud accepts only HTTPS URLs, on a certificate signed by a globally trusted authority, and on admin webhooks only from a listed set of ports that excludes 80. A self-signed certificate or a plain localhost address won't work, and Atlassian's docs describe no way to resend a delivery while you debug.
Set it up:
- Expose your local server through a tunnel with a trusted certificate.
- Register the URL with a JQL filter such as
project = TEST, so test traffic stays apart from production. - Check your signature code against Atlassian's test vector before you rely on real deliveries.
- Trigger real events: create an issue, transition it, add and edit a comment, and start and close a sprint.
- Try a bulk update and an issue deletion, so you see
Secondarywebhooks and a burst of traffic.
With Event Gateway: Hookdeck Inspect shows sample Jira payloads with no account or setup. The Hookdeck CLI forwards events to your machine with hookdeck listen and replays past ones, so you can repeat a delivery as often as you need.
Other Jira webhook limits
App webhook expiry. Webhooks registered with /rest/api/3/webhook expire after 30 days. Call Extend webhook life on a schedule to add another 30 days. An expired webhook stays available for up to 3 months, so you can still refresh it then.
Registration caps. That REST API allows 100 webhooks per app per tenant for a Connect app, and 5 per app per user on a tenant for an OAuth 2.0 app. On Data Center, webhooks past the default limit of 250 enabled may not be processed, with nothing in the logs. A property raises the limit.
Payload size. Webhooks larger than 25 MB aren't delivered, and Atlassian says that limit may change without notice. Issue events carry the issue with its fields, so a heavy issue makes a heavy delivery. If you only need to know that something changed, select Exclude body and fetch the details from the REST API.
IP allowlists. Jira Cloud sends from Atlassian's published outgoing ranges, so an endpoint behind an allowlist has to permit them. From January 1, 2027 requests from Atlassian, including webhooks, also come from 131.162.90.0/23. Add it before then unless you update your allowlist automatically from Atlassian's list.
Imported webhooks. After a site export or a copy to another instance, admin webhooks with a secret may not deliver until you rotate the secret.
Data Center queues. Webhooks have been asynchronous only since Jira 10.0. Past the default limits of 250 queued events, 5 worker threads, 500 in-flight dispatches and 5 connections per host, events are dropped and can't be recovered. You can tune these on 10.3.5 LTS and 10.6.0 or later, but not on 10.0.0 to 10.3.4 or 10.4 to 10.5. Bulk operations are the likely trigger, so reconcile against the REST API.
Data Center signing. Its admin docs from 11.0 describe X-Hub-Signature with a secret, and also offer basic authentication. Older versions' pages don't mention a secret, so check your own instance.
Automation webhooks. Jira Service Management's legacy automation webhooks have their own rules: 5 seconds to connect, 20 seconds for a response and no retries. Atlassian plans to phase them out.
With Event Gateway: Point one or two Jira webhooks at Hookdeck and fan events out to as many destinations as you need, which keeps you under registration caps. You set a maximum delivery rate, Hookdeck queues what's above it, and a transformation can strip or reshape large payloads before they reach your service.
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.