Jira

What it does

• A Stoaken webhook sent as a Jira issue creates an issue in one Jira Cloud project when a release is submitted for review.
• The summary is "Review Release v1.4.0 of Brand · Theme". The description says how many changes it has and links to the release in Stoaken.
• It uses a Jira API token you create. There's no Atlassian app or OAuth.

Before you start

• Brand Admin on the Brand (webhooks are part of the Team plan).
• Jira Cloud, and an Atlassian account with Browse projects and Create issues in the project. Issues are created as that account, so a shared service account reads best.
• An API token for that account, from your Atlassian account's Security > API tokens. Tokens expire after at most a year (Atlassian).
• The project key (the DS in DS-42) and the name of an issue type in that project, like Task.

Setup

1. Create the API token and copy it.
2. In Stoaken, go to Settings > Webhooks and choose Add a webhook:
   • Send as: Jira issue
   • Address: https://YOUR-SITE.atlassian.net/rest/api/3/issue
   • Account email: the account the token belongs to
   • API token: the token. It's stored encrypted and never shown again.
   • Project key and Issue type
   • Events: Release submitted for review (the only one this format takes).
3. With a token with scopes, use https://api.atlassian.com/ex/jira/CLOUD-ID/rest/api/3/issue instead: scoped tokens only work through Atlassian's API gateway. Give the token read:jira-work and write:jira-work.

Configuration

• The request is POST /rest/api/3/issue with fields.project.key, fields.issuetype.name, fields.summary and fields.description in Atlassian Document Format, sent with Authorization: Basic base64(email:token) (Atlassian).
• No labels, assignee or custom fields are set, so the project's create screen only needs summary and description. A project that makes other fields required refuses the issue.
• Stoaken only sends the token to https://SITE.atlassian.net/rest/api/3/issue or the api.atlassian.com/ex/jira/CLOUD-ID address, and the database refuses any other.
• More on formats: /docs/webhooks.

Try it

1. On the webhook, choose Send test. Stoaken reads the project (GET /rest/api/3/project/KEY) instead of creating an issue: it passes when the token works, the account can see the project, and the issue type exists there.
2. In the webhook lab, choose Send a sample with Release submitted for review. A real issue marked [Test] is created; delete it afterwards.
3. Submit a release for review and open the new issue's link.

Troubleshooting

• 401: the email or token is wrong, or the token expired. A token with scopes doesn't work on the site address at all: use the api.atlassian.com address.
• 403: the account can't create issues in that project.
• 404 on Send test: the project key is wrong, or the account can't see the project.
• Project DS has no issue type "Task": use one of the types Send test lists.
• 400 with a field name: Jira's reason shows in Recent deliveries, such as a field the project requires that Stoaken doesn't fill.

Limits

• Only Release submitted for review makes an issue. Stoaken doesn't comment on or close it when the release is published or rejected, because it doesn't keep track of the issue it made.
• One project per webhook; a Brand has at most 10 webhooks.
• Atlassian recommends OAuth for apps and says apps collecting API tokens don't meet its security requirements; this is a token you create and manage, scoped to one account.
• Failed deliveries retry for about a day (/docs/webhooks), so a long Jira outage can still mean a missed issue.