> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cogniscape.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira

> Set up a Jira webhook to capture issue lifecycle, sprint, and project activity in your knowledge graph.

The Jira integration captures issue lifecycle activity: created and updated issues, assignments, comments, status transitions, sprint movement, and project changes. Combined with GitHub and AI coding session data, this gives Cogniscape a complete picture of **what** your team is working on, **who** is involved, and **how** work moves from backlog to delivery.

This setup needs to be done **once per Jira site** (or for each Jira instance you want Cogniscape to observe). Only a **Jira administrator** can create and manage webhooks.

<Note>
  Both the Webhook URL and the signing secret are exclusive to your account. Keep the secret private — the endpoint rejects every request that does not include the matching secret.
</Note>

## Choose exactly one setup path

Jira Cloud and Jira Data Center / Server use different authentication mechanisms. Follow the section that matches your deployment — do not configure both for the same Jira instance.

## Jira Cloud

Use this path only when your Jira is hosted by Atlassian Cloud.

<Steps>
  <Step title="Open Jira webhook settings">
    In Jira Cloud, go to **Settings → System → Webhooks**, then create a new webhook.
  </Step>

  <Step title="Give it a label">
    Use something descriptive like **Cogniscape** so you can identify it later.
  </Step>

  <Step title="Paste the Webhook URL">
    Use the following URL, replacing `<your-customer-key>` with the key from the [Customer Portal](https://customer.cogniscape.app/):

    ```
    https://api.cogniscape.app/api/v1/events/jira/<your-customer-key>
    ```
  </Step>

  <Step title="Add the signing secret">
    Paste the secret from the [Customer Portal](https://customer.cogniscape.app/) (**Get Started → Jira Integration**) into Jira's **Secret** field. Cogniscape uses it to verify that incoming events are genuinely from your Jira site.

    <Warning>
      Do not click **Generate secret**. That button makes Jira create its own value, but Cogniscape and Jira must use the same secret already registered for your account. Jira may warn that the secret cannot be displayed again after saving — that's fine, paste the Cogniscape secret and save.
    </Warning>
  </Step>

  <Step title="Choose which events to send">
    Select the development activity events Cogniscape uses to build the Jira layer of your graph:

    * **Issue**: created, updated, deleted
    * **Comment**: created, updated, deleted
    * **Worklog**: created, updated, deleted
    * **Issue link**: created, deleted
    * **Sprint**: created, updated, deleted, started, closed
    * **Project**: created, updated, deleted
    * **Version**: created, released (moved, merged, updated, and unreleased are optional)

    <Tip>
      Leave **Board**, **Issue Type**, **User**, **Filter**, **Attachment**, **Entity property**, and **Feature status change** unchecked. Those are configuration or admin events, not development activity.
    </Tip>
  </Step>

  <Step title="Review delivery options and save">
    Leave **Exclude body** unchecked — Cogniscape needs the JSON event body.

    JQL is optional. Leave it blank to receive all projects, or add a filter to restrict issue events. Sprint, Version, and Board events are sent for all projects and do not follow the JQL filter.
  </Step>
</Steps>

## Jira Data Center / Server

Use this path only when your organization hosts Jira Data Center or Jira Server.

<Steps>
  <Step title="Open admin webhooks">
    In Jira administration, go to **System → WebHooks → Create**.
  </Step>

  <Step title="Paste the Webhook URL">
    Use the same URL as above, with your customer key from the [Customer Portal](https://customer.cogniscape.app/):

    ```
    https://api.cogniscape.app/api/v1/events/jira/<your-customer-key>
    ```
  </Step>

  <Step title="Add the custom HTTP header">
    Add this header so Cogniscape can authenticate requests from your Jira instance, using the secret from the [Customer Portal](https://customer.cogniscape.app/):

    ```
    X-Cogniscape-Token: <your-jira-webhook-secret>
    ```
  </Step>

  <Step title="Select the same development events">
    Use the same event selection from the Jira Cloud section: **Issue**, **Comment**, **Worklog**, **Issue link**, **Sprint**, **Project**, and **Version**. Leave configuration and admin events unchecked.
  </Step>

  <Step title="Leave body enabled, save, and check egress">
    Leave **Exclude body** unchecked, then save. Make sure your Jira server can make outbound HTTPS requests to `https://api.cogniscape.app` through your egress firewall.
  </Step>
</Steps>

<Warning>
  Create the webhook from the admin **WebHooks** screen above — that webhook type does not expire. Avoid REST or dynamic webhooks, which expire after 30 days.
</Warning>

## Verify the webhook

After saving, trigger a test by creating or updating an issue in Jira. Check the webhook delivery log to confirm events are being sent with a `200` response.

## Supported resources

Cogniscape processes these Jira webhook resource types:

| Resource     | Actions                              | What it captures                                                                           |
| ------------ | ------------------------------------ | ------------------------------------------------------------------------------------------ |
| `Issue`      | create, update, delete               | Title, key, status, priority, assignee, labels, description, and previous state on updates |
| `Comment`    | create, update, delete               | Comment body on issues — discussions, decisions, and context                               |
| `Worklog`    | create, update, delete               | Time logged against issues                                                                 |
| `Issue link` | create, delete                       | Relationships between issues (blocks, relates to, duplicates)                              |
| `Sprint`     | create, update, delete, start, close | Sprint name, state, and dates                                                              |
| `Project`    | create, update, delete               | Project key, name, and metadata                                                            |
| `Version`    | create, release                      | Release version name and status                                                            |

<Note>
  Resources not listed above are received but silently ignored. Selecting only the events above keeps your knowledge graph free of configuration and admin noise.
</Note>

## Why the secret matters

Cogniscape verifies every incoming Jira event against the secret saved in the Customer Portal before processing it. Without a matching secret, webhook events are rejected.

<Warning>
  Treat the secret as sensitive. If it's exposed, regenerate it in the [Customer Portal](https://customer.cogniscape.app/) and update the Jira webhook (Cloud secret field or Data Center header) before relying on new events. Old secrets stop working immediately after rotation.
</Warning>