Jira webhooks: admin webhooks, JQL filters, Send web request and retries

Jira Cloud calls your URL when an issue or another item changes, either from an admin webhook (an HTTP POST with a JSON body) or from an Automation rule using the Send web request action. The quickest way to inspect the payload is to drop a free bin URL into either sender and edit an issue (no signup, 48 hours, 100 requests a day). Below we cover setup, how the two senders compare, the payload structure, retries and signing, and Automation rules.

Point an admin webhook at a bin

1. Open view.webhooks.page to create a free bin, or run curl -X POST https://webhooks.sh/v1/bins to get an ingest_url and view_url.
2. In Jira, go to Settings > System, pick WebHooks under Advanced (you'll need the Administer Jira global permission), and create a webhook, or register it over the REST API at /rest/webhooks/1.0/webhook.
3. Paste the bin's ingest URL with a path, like https://<bin>.webhooks.page/jira/{issue.key}. Jira replaces variables such as {issue.key}, {issue.id} or {project.key} when it fires, so each request's path shows the issue key, and the bin runs over HTTPS on port 443, which Jira allows.
4. Add a JQL filter like project = ABC, or leave it blank to match every issue.
5. Tick Issue created and Issue updated, save, and edit an issue. The bin answers 200, so Jira counts the delivery as a success.

# 1. Create a free bin (or open view.webhooks.page)
curl -X POST https://webhooks.sh/v1/bins

# 2. Jira: Settings > System > WebHooks, create one:
#    URL:    https://<bin>.webhooks.page/jira/{issue.key}
#    JQL:    project = ABC
#    Events: Issue created, Issue updated
# 3. Edit an issue, then read the capture:
curl -H "x-view-key: <view key>" \
  https://view.webhooks.page/api/bins/<bin>/deliveries

Admin webhook or Automation Send web request

An admin webhook sends a fixed JSON body for the events you pick. You can filter it with JQL (though sprint and version events ignore the filter), sign it with a secret, and rely on Jira to retry failed deliveries.

The Send web request action is a step inside a Jira Automation rule: you pick the payload (Work item data (Jira format), Work item data (Automation format) or Custom format), set your own headers, and pass the response into later steps in the rule. The Incoming webhook trigger goes the other way, where Jira receives an HTTP request and starts a rule.

The jira:issue_updated payload

Every callback includes webhookEvent (such as jira:issue_created, jira:issue_updated or jira:issue_deleted), a timestamp in milliseconds, and the data for the item.

Issue events add issue_event_type_name, the issue object with its key and fields, and the user who made the change. On updates, a changelog lists every modified field with its fromString and toString values, while bulk edits attach bulkOperationMetaData. Keep two quirks in mind: deleting a project won't fire issue_deleted for its issues, and attachments added in the create dialog show up inside jira:issue_created rather than firing attachment_created.

{
  "timestamp": 1606480436302,
  "webhookEvent": "jira:issue_updated",
  "issue_event_type_name": "issue_generic",
  "issue": {
    "id": "99291",
    "key": "JRA-20002",
    "fields": {
      "summary": "I feel the need for speed",
      "labels": ["UI", "dialogue", "move"],
      "priority": { "name": "Minor", "id": "3" }
    }
  },
  "user": { "displayName": "Bryan Rollins [Atlassian]" },
  "changelog": {
    "id": 10124,
    "items": [
      {
        "field": "summary",
        "fromString": "What is going on here?????",
        "toString": "A new summary."
      }
    ]
  }
}

Retries, signing and the X-Atlassian headers

Jira only treats an HTTP 200 as a success. It retries up to 5 times, waiting 5 to 15 minutes after each attempt, on 408, 409, 425, 429 and 5xx responses, connection failures and timeouts, so your receiver can see the same event more than once. Jira adds these headers, and all of them stay visible in a bin:

• X-Atlassian-Webhook-Identifier stays the same across all retries of a delivery.
• X-Atlassian-Webhook-Retry holds the retry count and only appears on retried deliveries.
• X-Atlassian-Webhook-Flow is Primary (sent within 30 seconds) or Secondary (from bulk or cascading updates, taking up to 15 minutes).

If you set a secret on an admin webhook, Jira signs the raw body in X-Hub-Signature as sha256= followed by the hex HMAC, the same WebSub format Bitbucket webhooks use. You can't view the secret again after saving, and you can check a captured request against your secret with the HMAC signature verifier.

A free bin returns 429 (daily_cap_reached) after 100 requests in a day, which triggers Jira's retries, so narrow your JQL on busy projects. If you need the bin past 48 hours, claim it with a free Google sign-in to keep the same URL and 30 days of rolling history at 100 requests a day.

Automation: Send web request and incoming webhooks

To see what a Send web request step actually sends after smart values are filled in, set its URL to a bin and run the rule. Because a free bin always answers with a fixed 200 body like {"ok":true,"delivery_id":"..."}, any later rule steps that read the response will only see that JSON. Also watch out for values marked Hide in the action: Jira turns them into asterisks once saved, and they get wiped if you duplicate or export the rule.

For the Incoming webhook trigger, callers pass the rule's secret in X-Automation-Webhook-Token (or in the URL) and the rule reads the body from {{webhookData}}. Point your script at a bin first to check the payload, though X-Automation-Webhook-Token has token in the name so its value shows as redacted in the viewer.

FAQ

How do I test a Jira webhook?

Create a free bin, paste its ingest URL into an admin webhook (Settings > System, then WebHooks under Advanced) or an Automation Send web request action, and create or edit an issue. The JSON POST arrives live in the browser with no signup.

What is the difference between a Jira webhook and Send web request?

An admin webhook sends a fixed JSON payload for the events you select, and supports JQL filters, an optional X-Hub-Signature secret, and automatic retries. Send web request is a step in an Automation rule where you pick the body format and custom headers, and you can use the HTTP response in later steps.

Does Jira retry failed webhooks?

Yes, Jira retries up to 5 times, spaced 5 to 15 minutes apart, on 408, 409, 425, 429, 5xx, timeouts and connection failures. Only a 200 response counts as a success, so use the X-Atlassian-Webhook-Identifier header to deduplicate deliveries.

Can I filter a Jira webhook with JQL?

Yes, JQL filters work for issue, comment, worklog, attachment, issue link and issue property events. Leaving the filter empty matches all issues, and sprint and version events ignore the filter entirely.

Why won't Jira accept my webhook URL?

Admin webhook URLs must use HTTPS with a certificate from a globally trusted authority on an allowed port such as 443 or 8443 (port 80 is rejected, and Jira follows at most 5 redirects). If the URL saves but nothing shows up, see the webhook not received guide.

How do I put the issue key in a Jira webhook URL?

Add {issue.key} to the path when you save the webhook URL. Jira replaces it when sending, so /webhook/{issue.key} arrives as /webhook/EXA-1.