How to Capture a Webpage Screenshot and Attach It to a Jira Issue with n8n
Build an n8n workflow that captures a webpage as an image, passes it as binary data, and uploads it to a Jira issue.
To attach a webpage screenshot to a Jira issue with n8n, make the screenshot step return an image as binary data, pass that binary file to an HTTP Request node, and send a multipart upload to Jira’s attachment endpoint. Screenshot capture and Jira upload are separate operations: n8n documents Jira Software integration and HTTP Request for API calls, but the exact screenshot operation and binary property depend on the capture tool and your n8n version.
This guide uses a capture-provider placeholder for the do-it-yourself workflow. Replace it with a browser automation process or screenshot API that you have configured and verified to return an image file. Then configure the Jira upload as described below. For Jira Cloud, the endpoint is POST /rest/api/3/issue/{issueIdOrKey}/attachments; the multipart field must be named file and the request must include X-Atlassian-Token: no-check (Atlassian attachment API).
1. Prepare the workflow inputs
Use a trigger that supplies at least two values: the webpage URL to capture and the Jira issue key, such as https://example.com and WEB-123. A manual trigger is useful while building; a webhook or scheduled trigger can supply them in production.
Keep the issue key separate from the page URL. Validate both before making external requests: the URL should use an allowed scheme such as HTTPS, and the issue key should be present and refer to the intended Jira project. If the URL or issue key comes from an untrusted caller, apply your own access controls and URL allowlist before fetching it.
2. Capture the webpage as an image
Choose a capture method that can render the page and give n8n an image file. The research available for this guide does not verify a built-in current n8n screenshot node, a particular provider, or its exact binary property. Do not assume a JSON response containing an image URL is already a file: if the capture operation returns a URL, fetch that URL in a subsequent step and configure that fetch to return a file/binary result.
For browser automation, make sure the browser process can reach the page, wait for the page state you need, and save a PNG or JPEG. For a managed API, consult its current documentation for output format, authentication, full-page behavior, viewport options and response mode. In either case, confirm in an n8n execution that the output contains a binary entry with a filename and expected content type before wiring the upload.
Pass the binary result forward
- Inspect the capture node’s successful execution output and find the binary property name. It may be named differently by each node or configuration.
- Record the property name and the image MIME type and filename shown in the execution data.
- Ensure intermediate nodes preserve binary data. If a node transforms the item, check that it passes the binary property through along with the JSON issue key.
- Configure the Jira upload node’s binary input property to exactly match the observed name.
Keep the issue key in the JSON portion of the same item (or merge it back in deliberately) while carrying the screenshot in binary data. This avoids converting the image to base64 in ordinary JSON, which adds encoding overhead and can run into request or memory limits.
3. Upload the file to Jira Cloud
Use n8n’s Jira node if its current operation supports adding an attachment in your installed version. Otherwise, use an HTTP Request node to call the Jira API. n8n describes HTTP Request as the option for calling APIs when a dedicated integration does not expose an operation (n8n HTTP Request documentation).
For an HTTP Request node, set the method to POST, URL to https://YOUR-SITE.atlassian.net/rest/api/3/issue/{{ $json.issueKey }}/attachments, and authentication to your Jira Cloud credential. Select the node’s multipart/form-data body mode, add a form-data field named file, and set that field’s value source to the binary property observed in the capture output. Add the header X-Atlassian-Token with value no-check. Let n8n construct the multipart content type and boundary; do not replace it with a bare multipart/form-data header that omits the boundary.
Exact labels and binary mapping controls can vary with n8n versions. Verify the live node settings and the resulting request rather than copying an unverified click-by-click recipe. Use a Jira credential rather than embedding a password or API token in workflow expressions.
Direct Jira Cloud upload with cURL
This standalone example is useful for isolating Jira authentication, permission and attachment behavior from n8n. It assumes you already saved the screenshot as shot.png. Jira Cloud basic authentication uses the account email and an API token.
curl --fail-with-body --user 'you@example.com:YOUR_JIRA_API_TOKEN' \
-H 'X-Atlassian-Token: no-check' \
-F 'file=@shot.png;type=image/png' \
'https://YOUR-SITE.atlassian.net/rest/api/3/issue/WEB-123/attachments'A successful response returns attachment metadata as JSON. A successful HTTP status confirms Jira accepted the upload; still check the target issue to verify it is the intended attachment.
Direct Jira Cloud upload with Python
Install the dependency with python -m pip install requests. The file is streamed from disk as multipart form data.
import os
import requests
site = "https://YOUR-SITE.atlassian.net"
issue_key = "WEB-123"
email = os.environ["JIRA_EMAIL"]
api_token = os.environ["JIRA_API_TOKEN"]
with open("shot.png", "rb") as image:
response = requests.post(
f"{site}/rest/api/3/issue/{issue_key}/attachments",
auth=(email, api_token),
headers={"X-Atlassian-Token": "no-check", "Accept": "application/json"},
files={"file": ("shot.png", image, "image/png")},
timeout=90,
)
response.raise_for_status()
print(response.json())Direct Jira Cloud upload with Node.js
This example uses Node.js built-in fetch and FormData with a file stream converted to a Blob. Use a current Node.js version with these web APIs available. Do not set the multipart content-type header manually; fetch adds the boundary.
import { readFile } from "node:fs/promises";
const site = "https://YOUR-SITE.atlassian.net";
const issueKey = "WEB-123";
const email = process.env.JIRA_EMAIL;
const apiToken = process.env.JIRA_API_TOKEN;
const bytes = await readFile("shot.png");
const form = new FormData();
form.append("file", new Blob([bytes], { type: "image/png" }), "shot.png");
const auth = Buffer.from(`${email}:${apiToken}`).toString("base64");
const response = await fetch(
`${site}/rest/api/3/issue/${encodeURIComponent(issueKey)}/attachments`,
{
method: "POST",
headers: {
Authorization: `Basic ${auth}`,
"X-Atlassian-Token": "no-check",
Accept: "application/json",
},
body: form,
},
);
if (!response.ok) {
throw new Error(`Jira upload failed: ${response.status} ${await response.text()}`);
}
console.log(await response.json());4. Confirm the attachment and handle workflow outcomes
Use the upload response and a Jira issue check to confirm success. In n8n, decide whether a failed capture should stop the execution, be retried, or be recorded for review. Do not let an empty or error response continue into a file upload as if it were an image.
For reliable retries, consider that a timeout may occur after Jira accepted the file but before n8n received the response. A blind retry can create a duplicate attachment. Where duplicates matter, inspect the issue’s attachments or otherwise record the outcome before retrying. Keep an execution identifier, issue key and source URL in your operational logs, but avoid logging credentials or private page contents.
Jira Data Center is a separate setup
This endpoint and examples above target Jira Cloud. Jira Data Center has separate REST documentation and deployment-specific authentication and permissions. Confirm the base URL, supported API version, authentication method, attachment settings and permissions against the documentation for your exact Data Center version before adapting the workflow (Jira Data Center REST API documentation).
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. A single GET request captures a URL and returns an image or PDF; use this request step in place of managing a browser, then pass the returned image binary to the Jira upload step above. See the ScreenshotNeo API documentation for request options and n8n response handling.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpScreenshotNeo removes cookie banners, newsletter popups and chat widgets before the shot. Bot checks, blank pages and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Once n8n has the returned file as binary data, upload it to Jira using the multipart configuration above.
Sign up for ScreenshotNeo and get 1,000 screenshots a month free, with no card.
Troubleshooting
| Symptom | Likely cause | What to check or change |
|---|---|---|
| Jira rejects the request with a token or XSRF error | The required special header is missing or misspelled. | Send X-Atlassian-Token: no-check on the upload request. |
| Unsupported media type or malformed multipart request | The body was sent as JSON, or the multipart boundary is missing. | Use multipart/form-data mode and a field named file. Let n8n or the HTTP client generate the boundary. |
| Attachment field is empty or Jira says no file was provided | The binary property name does not match the capture output, or an intermediate node dropped the binary data. | Inspect the prior node’s binary output and configure the upload field to use that exact property. |
| 401 response | Authentication is missing, invalid or intended for a different Jira site. | Check the credential and site base URL. Use an authorized Jira Cloud account/API token or the configured OAuth credential. |
| 403 response | The account may lack Browse Projects or Create Attachments permission, or issue security may block access. | Check the project permission scheme, issue-level security and credential identity. |
| 404 response | The site URL or issue key may be wrong, or the user cannot see the issue. | Confirm the Jira site, issue key and browse access. |
| 413 response or size-limit message | The image exceeds the configured attachment size limit. | Check Jira attachment settings and reduce image dimensions or output quality at the capture step. Atlassian documents that the maximum is configurable (attachment settings). |
| Capture returned HTML or a blank image | The target may require authentication, client-side rendering, or more time before capture; a bot check or failed page load may also intervene. | Check the capture response type and page state. Configure supported authentication, wait conditions and error handling for the selected capture mechanism. |
| Upload times out but the issue may contain the file | The server may have accepted the upload while the response was lost. | Inspect the issue before retrying to avoid duplicate attachments. |
Performance, reliability and cost
- Rendering time: Page load time, client-side rendering and chosen wait condition determine capture duration. Avoid arbitrary long waits where a meaningful selector or readiness condition is available.
- Payload size: Full-page and high-resolution images can be large. Choose the smallest dimensions and format that preserve the detail needed in the Jira issue, and stay below the configured attachment limit.
- Binary handling: Keep screenshots as binary through n8n. Base64 JSON increases the payload and can add memory pressure.
- Retries: Retry transient capture failures with limits and backoff. Treat upload timeouts as ambiguous until Jira is checked; uploads are not automatically safe to repeat.
- Costs: Self-hosted browser automation uses your compute and maintenance. A managed capture API may charge according to its own plan and billing rules; verify those directly. Jira attachment storage and size constraints are governed by your Jira configuration and plan.
- Credentials: Store capture and Jira secrets in n8n credentials or a secret manager, restrict who can edit the workflow, and avoid putting secrets in URLs or execution logs.
FAQ
Can n8n take the screenshot without a separate capture tool?
The sources available for this guide do not establish a current built-in screenshot operation. Select a browser automation setup or screenshot API, then pass its image result to n8n as binary data.
Can I attach more than one screenshot?
Jira’s attachment operation accepts one or more multipart files. In n8n, confirm that your chosen node and binary mapping send each file under the required file form field.
Will Jira Cloud instructions work unchanged for Data Center?
No. Data Center uses separate REST documentation and deployment-specific configuration. Verify its endpoint, authentication and permissions before use.
How do I attach a screenshot of a private webpage?
The capture mechanism must be able to authenticate to that page, independently of Jira authentication. Use only a capture method with appropriate header, cookie or session handling, and prevent secrets from leaking into logs or the image.
