Jira Integration

The Jira sync adapter provides two-way synchronization between UserHero workflows and Jira Cloud projects. Push workflow items to Jira as issues, and receive status updates back through webhooks.

Prerequisites

A UserHero project on the Growth, Pro, or Pro Max plan
A Jira Cloud instance with project admin access
At least one workflow created in your project

Setup

1. Connect Jira

Go to your project Settings → Sync Adapters
Click Add Adapter → Jira
You'll be redirected to Atlassian's OAuth consent page
Authorize UserHero to access your Jira instance
Select the Jira site (if you have multiple)
You'll be redirected back to UserHero

2. Select a Project

After authorization, choose which Jira project to sync with:

Select a project from the dropdown (shows all projects you have access to)
Click Confirm

Each sync adapter instance connects one UserHero workflow to one Jira project.

3. Configure Status Mapping

Map your workflow statuses to Jira status categories. Jira uses status categories rather than exact status names:

Jira Category	Contains statuses like
To Do	Open, New, Backlog
In Progress	In Progress, In Review, In Development
Done	Done, Completed, Resolved, Closed

Default mapping (Issues workflow):

UserHero Status	Jira Category
Open	To Do
In Progress	In Progress
Resolved	Done
Closed	Done

Default mapping (Tickets workflow):

UserHero Status	Jira Category
New	To Do
Awaiting Response	To Do
In Progress	In Progress
Resolved	Done
Closed	Done

Default mapping (Leads workflow):

UserHero Status	Jira Category
New	To Do
Contacted	In Progress
Qualified	In Progress
Proposal	In Progress
Won	Done
Lost	Done

You can customize the specific Jira status within each category to match your project's workflow configuration.

Pushing Items to Jira

Once configured:

Open a workflow item
Click Push to Jira
A Jira issue is created in the connected project
The item's detail view shows an External Reference with a direct link to the Jira issue

The created Jira issue includes:

Summary from the workflow item title
Description from the workflow item description
Status mapped from the workflow status
Priority mapped from the workflow priority

Priority Mapping

UserHero	Jira
Low	Low
Medium	Medium
High	High
Urgent	Highest

Inbound Sync (Webhooks)

Jira sends webhook events when issues are updated. UserHero processes these to keep your workflow items in sync.

What syncs back

Jira Change	UserHero Update
Status changed	Workflow item status updated (via status category mapping)

Status is mapped first by Jira status category (To Do → open, In Progress → in-progress, Done → resolved), then by status name as a fallback.

Webhook setup

To enable inbound sync, create a webhook in your Jira Cloud instance:

Go to Jira Settings → System → Webhooks
Click Create a WebHook
Set the URL to: https://userhero.co/api/webhooks/jira
Under Events, select Issue → updated
Add an Authorization header with Bearer {your-webhook-secret}
Save the webhook

The webhook secret must match the JIRA_WEBHOOK_SECRET environment variable configured in your UserHero deployment.

Managing the Adapter

Disconnecting

Go to project Settings → Sync Adapters
Find the Jira adapter
Click Disconnect

Existing external references are preserved — the links to Jira issues still work.

Reconnecting

Reconnect anytime through the setup flow. The same Jira project can be re-selected to resume syncing from existing references.

Troubleshooting

Problem	Solution
Push fails with "unauthorized"	Reconnect the adapter — your OAuth token may have expired
Wrong issue type created	Check Jira project's default issue type settings
Status not mapping correctly	Verify the Jira status belongs to the expected category in Jira project settings
Can't see my project	Ensure you have project admin access in Jira

Jira