Jira Automation

Jira Automation can dispatch a queued Agentic Unit job from an issue event or comment. The configured endpoint and credential are currently different in Development and Production.

Choose The Correct Environment Setup

Environment	Endpoint	Credential and payload
Development	https://api.dev.ai-agent.vwfs.io/webhook/jobs/jira-events	Legacy Jira webhook key and v1 payload
Production	https://api.ai-agent.vwfs.io/webhook/jobs/v2/jobs/dispatch	Scoped Bearer trigger token and v2 payload

Development remains on the legacy Jira webhook because the new dispatch endpoint could not be allowlisted in Jira there. This is an intentional environment-specific exception, not an automatic fallback. Do not send the v2 payload to the Development URL, and do not use a legacy webhook key with the Production dispatch endpoint.

For environments not listed above, ask the Agentic Unit platform team which setup is approved before creating the rule.

Before You Begin

An Agentic Unit administrator must onboard the team and Jira project and make the required agent available to the team. They must then provide the credential for the target environment:

• Development uses the legacy Jira webhook key associated with the team, project, agent, and GitHub App installation.
• Production uses a v2 trigger token with channel jira, optionally restricted to the Jira project and a default or allowed agent.

Both credentials are sent as Bearer tokens and are shown only when created. Store them as secrets in Jira Automation. Never paste them into a ticket, comment, screenshot, or documentation page.

Production: V2 Dispatch

Use this request in Production:

POST https://api.ai-agent.vwfs.io/webhook/jobs/v2/jobs/dispatch
Authorization: Bearer <production-trigger-token>
Content-Type: application/json

A minimal Production payload is:

{
  "prompt": "Work on Jira issue {{issue.key}}. Follow its acceptance criteria and report the result in the issue.",
  "context": {
    "issues": [
      { "issueId": "{{issue.key}}" }
    ]
  },
  "notify": {
    "email": "{{issue.assignee.emailAddress}}"
  },
  "metadata": {
    "jiraIssueKey": "{{issue.key}}"
  }
}

prompt is the instruction passed to the agent. Keep the Jira issue key in the prompt as well as context.issues so both the agent and the audit record identify the task.

notify.email is optional. When present, Agentic Unit sends a notification after the job reaches COMPLETED, FAILED, or CANCELLED. It does not define the security identity for the run; the trigger token supplies the team and channel.

If the repository and base branch are known, provide them explicitly:

{
  "prompt": "Implement the requirements in {{issue.key}} and run the repository tests.",
  "context": {
    "issues": [
      { "issueId": "{{issue.key}}" }
    ],
    "repositories": [
      { "name": "example-repository", "branchName": "develop" }
    ]
  }
}

The GitHub organisation and installation are resolved from the team when they are omitted. The repository must be accessible through that team's GitHub App installation. agentId is optional when the trigger token has a default agent; if supplied, it must be allowed by the token.

Development: Legacy Jira Webhook

Use this request in Development until the v2 dispatch endpoint has been allowlisted in Jira:

POST https://api.dev.ai-agent.vwfs.io/webhook/jobs/jira-events
Authorization: Bearer <development-jira-webhook-key>
Content-Type: application/json

The Development rule must use the legacy payload:

{
  "webhookEvent": "jira:issue_updated",
  "initialPrompt": "This job was triggered by Jira Automation. Work on Jira issue {{issue.key}}, follow its acceptance criteria, and report the result in the issue.",
  "email": "{{issue.assignee.emailAddress}}"
}

initialPrompt is the instruction used by the legacy handler. Keep the issue key in that text because v1 has no context.issues field. The team, Jira project, default agent, and GitHub App installation come from the legacy webhook key.

Existing Development rules may retain the legacy email field, but it does not provide the explicit notify.email semantics of the v2 dispatch request.

Configure The Jira Rule

Create a separate rule for each target environment. Each rule needs one comment condition followed by its environment-specific web request; do not combine the Development and Production URLs, credentials, or payloads.

1. Create A Rule

Open the Jira project, then go to Project settings -> Automation -> Create rule.

2. Select The Trigger

Choose Issue commented or another event appropriate for the workflow.

3. Add The Comment Condition

Add one Advanced compare condition. Set the first value to {{comment.body}}, choose contains, and set the second value to the command configured for the target environment. Do not allow every comment to start an agent, and do not add a separate assignee condition.

4. Configure The Development Web Request

In the Development rule, add Send web request and configure all of these values together:

• URL: https://api.dev.ai-agent.vwfs.io/webhook/jobs/jira-events
• Method: POST
• Header: Authorization: Bearer <development-jira-webhook-key>
• Body type: custom JSON data
• Body: the Development v1 payload shown in Development: Legacy Jira Webhook

Save the credential through Jira's secret-value control. The screenshot must show a placeholder or secret reference, never the actual key.

5. Configure The Production Web Request

In the Production rule, add Send web request and configure all of these values together:

• URL: https://api.ai-agent.vwfs.io/webhook/jobs/v2/jobs/dispatch
• Method: POST
• Header: Authorization: Bearer <production-trigger-token>
• Body type: custom JSON data
• Body: the Production v2 payload shown in Production: V2 Dispatch

Save the token through Jira's secret-value control. Do not reuse the Development webhook key or legacy payload.

Responses

Production v2 returns HTTP 202 with a traceable request ID:

{
  "message": "Agent job dispatched successfully",
  "requestId": "00000000-0000-0000-0000-000000000000",
  "status": "QUEUED"
}

Development v1 returns HTTP 200:

{
  "message": "Agent start request accepted"
}

Common failures are:

• 400 — the Production payload is invalid or no default agentId is available.
• 401 — the Authorization header is missing, the credential is invalid, or the credential type does not match the endpoint.
• 403 — the credential was revoked or its project or agent restriction does not allow the request.

Test The Rule

Test the rule with an issue owned by the onboarded team. Confirm that:

• the rule runs only when its conditions match;
• the URL, credential, and body all match the same environment row;
• the Authorization header and JSON content type are present;
• the payload contains the Jira issue key;
• Production returns HTTP 202, a requestId, and QUEUED;
• Development returns HTTP 200 and Agent start request accepted;
• the job reaches a terminal status and produces the expected Jira and code result for the selected agent's skills.

Check the Jira Automation audit log first when a rule fails.

Migration Status

Production has migrated from the v1 Jira webhook to v2 dispatch. Development must remain on the v1 endpoint until the Production-style dispatch URL is allowlisted there.

The formats are not interchangeable:

Development v1	Production v2
Legacy Jira webhook key	Scoped Bearer trigger token
webhookEvent	Removed; the token identifies the channel
initialPrompt	prompt
Issue key embedded in prompt text	context.issues[].issueId plus the prompt
Legacy email	notify.email
/webhook/jobs/jira-events	/webhook/jobs/v2/jobs/dispatch

When Development allowlisting changes, migrate its URL, credential, and payload together. Until then, do not partially copy the Production setup into the Development rule.