# Jira webhook

Source: https://docs.coderhelm.com/api/reference/webhooks/receive-jira-webhook

`POST /webhooks/jira/{token}`

For a plain Jira webhook, when the CoderHelm Jira app can't be installed. The URL holds a token generated for your team on the Jira page of the dashboard. If you also generated a secret there, every request must carry `X-Hub-Signature`: `sha256=` and the hex HMAC-SHA256 of the raw body, keyed with that secret. Jira Cloud signs webhooks this way when you set the secret on the webhook; a Jira automation can send the header itself.

## Authentication

Verified by its signature header. See [Webhooks](https://docs.coderhelm.com/api/webhooks).

## Parameters

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes | The webhook token from the Jira page of the dashboard. |

## Request body

`application/json`: The Jira event.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `coderhelm` | JiraRepoPin or null | no | Which repository a Jira ticket goes to. May also be sent at the top level. |
| `coderhelm.repo_name` | string | yes | The repository's name. |
| `coderhelm.repo_owner` | string | yes | The repository's owner. |
| `comment` | JiraComment or null | no | The comment in a Jira comment event. |
| `comment.author` | JiraUser | yes | A Jira user. |
| `comment.author.displayName` | string | yes | The user's name. An issue assigned to a user whose name contains "CoderHelm" starts a run. |
| `comment.body` | string | yes | What the comment says. It is sent to the run as feedback. |
| `issue` | JiraIssue | yes | The issue in a Jira event (the fields CoderHelm reads). |
| `issue.fields` | JiraIssueFields | yes | The issue fields CoderHelm reads. |
| `issue.fields.assignee` | JiraUser or null | no | A Jira user. |
| `issue.fields.assignee.displayName` | string | yes | The user's name. An issue assigned to a user whose name contains "CoderHelm" starts a run. |
| `issue.fields.description` | string or null | no | The body. The coder reads it as the ticket. |
| `issue.fields.labels` | array of string | yes | Labels. `coderhelm`, or one starting `coderhelm:`, starts a run. |
| `issue.fields.project` | JiraProject | yes | A Jira project. |
| `issue.fields.project.key` | string | yes | The project key. |
| `issue.fields.summary` | string | yes | The title. It becomes the run's title. |
| `issue.key` | string | yes | The issue key. |
| `webhookEvent` | string | yes | The event, such as `jira:issue_created`, `jira:issue_updated` or `comment_created`. An event whose name contains `comment` retries a failed run or sends feedback to an open pull request; other issue events can start a run. |

## Responses

### 200

Accepted (whether or not it started anything).

### 400

The body is not JSON.

### 401

Unknown token, or the signature is missing or wrong.

## Example request

cURL:

```bash
curl -X POST 'https://api.coderhelm.com/webhooks/jira/string' \
  -H 'Content-Type: application/json' \
  -d '{
  "coderhelm": {
    "repo_name": "web",
    "repo_owner": "acme"
  },
  "issue": {
    "fields": {
      "labels": [
        "coderhelm"
      ],
      "summary": "Add rate limiting to the login form"
    },
    "key": "WEB-42"
  },
  "webhookEvent": "jira:issue_updated"
}'
```

TypeScript:

```ts
const res = await fetch("https://api.coderhelm.com/webhooks/jira/string", {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "coderhelm": {
        "repo_name": "web",
        "repo_owner": "acme"
      },
      "issue": {
        "fields": {
          "labels": [
            "coderhelm"
          ],
          "summary": "Add rate limiting to the login form"
        },
        "key": "WEB-42"
      },
      "webhookEvent": "jira:issue_updated"
    }),
});
if (!res.ok) {
  const { error, code } = await res.json();
  throw new Error(`${res.status} ${code}: ${error}`);
}
const data = await res.json();
```

Python:

```python
import requests

body = {
    "coderhelm": {
        "repo_name": "web",
        "repo_owner": "acme",
    },
    "issue": {
        "fields": {
            "labels": [
                "coderhelm",
            ],
            "summary": "Add rate limiting to the login form",
        },
        "key": "WEB-42",
    },
    "webhookEvent": "jira:issue_updated",
}
res = requests.request("POST", "https://api.coderhelm.com/webhooks/jira/string", json=body)
if not res.ok:
    raise RuntimeError(f"{res.status_code}: {res.json().get('error')}")
data = res.json()
```