# Linear Integration
### Overview
[Linear](https://linear.app/) is a modern issue tracking tool built for high-performance software teams. This integration listens for Linear webhooks and turns issue activity into actionable alerts on the platform.
Whenever a new issue is created or an existing one is updated, the platform opens an alert. When the issue is marked as **Done** or **Canceled**, the alert is automatically resolved.
This is useful when your engineering team uses Linear to track production incidents, bugs, or urgent tasks, and you want that activity to flow into the same on-call and escalation workflows you already use for monitoring alerts.
### Integration Flow
1. An issue is created or updated in Linear — manually by a team member, via API, or through another automation.
2. Linear sends a webhook POST request to the platform endpoint, signed with an HMAC signature.
3. The platform classifies the event:
* `create` on an Issue → opens a new alert
* `update` that leaves the issue open → keeps the alert open (updates the timeline)
* `update` that moves the issue to a completed or canceled state → resolves the alert
* `remove` (issue deleted) → resolves the alert
4. The alert's priority is derived from the Linear issue's **priority** field and mapped to an internal priority level.
### Webhook Payload Schema
```json
{
"action": "create | update | remove",
"type": "Issue",
"actor": {
"id": "string",
"name": "string",
"email": "string",
"url": "string",
"type": "user"
},
"createdAt": "ISO8601 timestamp",
"data": {
"id": "uuid",
"identifier": "string",
"number": 0,
"title": "string",
"description": "string",
"priority": 0,
"priorityLabel": "string",
"state": {
"id": "uuid",
"name": "string",
"type": "unstarted | started | completed | canceled | triage",
"color": "string"
},
"team": {
"id": "uuid",
"key": "string",
"name": "string"
},
"labels": [
{"id": "uuid", "name": "string", "color": "string"}
],
"assignee": {"id": "uuid", "name": "string", "email": "string"},
"url": "string",
"completedAt": "ISO8601 timestamp"
},
"updatedFrom": {},
"url": "string",
"organizationId": "uuid",
"webhookTimestamp": 0,
"webhookId": "uuid"
}
```
Only payloads with `type: "Issue"` are processed. Comment, Project, and other resource types are ignored.
### Setup
#### Step 1 — Create an Alert Source on the Platform
1. Navigate to **Sources → Add Source**.
2. Search for **Linear** and select it.
3. Give the source a name and click **Save**.
4. Copy the **ITOC360 URL** and **Token** — you will need them in the next step.
#### Step 2 — Open Linear Settings
In your Linear workspace, click the workspace avatar in the top-left and select **Settings**. You can also use the keyboard shortcut **G** then **S**.
#### Step 3 — Go to the API Section
In the Settings sidebar, scroll to **Administration** and click **API**. This page shows your OAuth applications, webhooks, and API keys.
#### Step 4 — Create a Webhook
Under the **Webhooks** section, click **+ New webhook**. Fill in the form:
* **Label** — a descriptive name, for example `itoc360`.
* **URL** — paste the ITOC360 URL you copied in Step 1, including the `?token=...` query parameter.
* **Data change events** — enable **Issues**. You can also enable **Comments** if you want comment activity to flow through, but only Issue events are processed by this integration.
* **Team selection** — choose `All public teams` or a specific team depending on scope.
Click **Create webhook**.
> Linear will display a **Signing secret** on the webhook detail page. Store it securely — it is used to verify that incoming webhooks genuinely come from Linear. You can also reveal or rotate it later from the same page.
#### Step 5 — Verify the Webhook
After creation, you will land on the webhook detail page. Confirm:
* **Delivery status** is `Enabled`.
* **URL** matches the ITOC360 URL.
* **Data change events** shows `Issue` (and `Comment` if you enabled it).
* **Receive events from** matches your team selection.
The **Delivery failures** section at the bottom will remain empty as long as the platform is reachable \
and responds with a 2xx status.
#### Step 6 — Trigger a Test Issue
Create a new issue in Linear to verify the end-to-end flow:
1. Open any team's issue view and click **New issue** (or press **C**).
2. Give it a title, description, priority, and assignee.
3. Click **Create issue**.
\
Within a second or two, the alert should appear on the platform under the source you created in Step 1. Change the issue's state to **Done** to confirm that the alert is automatically resolved.
### Event Behavior
The platform processes Linear events using the `action` field and the issue's state.
| Linear Event | Platform Behavior |
| ----------------------------------------- | ------------------------------------------------- |
| `action: create` | Opens a new alert |
| `action: update`, state still open | Appends an event to the existing alert's timeline |
| `action: update`, `state.type: completed` | Resolves the alert |
| `action: update`, `state.type: canceled` | Resolves the alert |
| `action: remove` | Resolves the alert |
| Any event with `type != "Issue"` | Ignored |
All events from the same Linear issue are linked to the same alert through a fingerprint derived from the issue's UUID. This means priority changes, title edits, description updates, and state transitions all flow into a single alert — no duplicates.
### Sample Payloads
The following payloads were captured during integration testing.
**ALERT — issue created with Urgent priority:**
```json
{
"action": "create",
"actor": {
"id": "1cbbf81a-29db-4874-87b3-e1d0c64dd8b9",
"name": "abc@.com.tr",
"email": "abc@.com.tr",
"type": "user"
},
"createdAt": "2026-04-17T14:06:27.112Z",
"data": {
"id": "5cc28a8c-7259-4548-8c93-1c98ada785cb",
"identifier": "ITO-5",
"number": 5,
"title": "Production API responding with 500 errors",
"description": "Multiple 500 errors reported on /api/orders endpoint since 14:30. Investigating.",
"priority": 1,
"priorityLabel": "Urgent",
"state": {
"id": "8eef44ea-edc9-4f7e-8d3a-1c446c510fe6",
"name": "Todo",
"type": "unstarted",
"color": "#e2e2e2"
},
"team": {"id": "9ede9327-af3e-468a-9b22-9181453feb1b", "key": "ITO", "name": "Itoc360space"},
"labels": [{"id": "2d90f79a-73dc-4879-a6de-db5c93e71a91", "name": "Bug", "color": "#EB5757"}],
"url": "https://linear.app/itoc360space/issue/ITO-5/production-api-responding-with-500-errors"
},
"type": "Issue",
"organizationId": "d05809de-2327-4443-a202-e96ec357a5e4",
"webhookTimestamp": 1776434787544,
"webhookId": "a32c7c48-0b88-4baf-87d9-468c8e4dea48"
}
```
**RESOLVE — issue moved to Done:**
```json
{
"action": "update",
"actor": {
"id": "1cbbf81a-29db-4874-87b3-e1d0c64dd8b9",
"name": "abc@.com.tr",
"email": "abc@.com.tr",
"type": "user"
},
"createdAt": "2026-04-17T14:08:09.041Z",
"data": {
"id": "5cc28a8c-7259-4548-8c93-1c98ada785cb",
"identifier": "ITO-5",
"title": "Production API responding with 500 errors",
"priority": 2,
"priorityLabel": "High",
"completedAt": "2026-04-17T14:08:09.026Z",
"state": {
"id": "f2ea18b1-0b90-46d1-b9c3-0daae99ceffc",
"name": "Done",
"type": "completed",
"color": "#5e6ad2"
},
"url": "https://linear.app/itoc360space/issue/ITO-5/production-api-responding-with-500-errors"
},
"updatedFrom": {
"stateId": "8eef44ea-edc9-4f7e-8d3a-1c446c510fe6",
"completedAt": null
},
"type": "Issue",
"organizationId": "d05809de-2327-4443-a202-e96ec357a5e4",
"webhookTimestamp": 1776434889612,
"webhookId": "a32c7c48-0b88-4baf-87d9-468c8e4dea48"
}
```
### Field Mapping Reference
| Payload Field | Description |
| -------------------- | ------------------------------------------------------------------------------- |
| `action` | Event type: `create`, `update`, or `remove` |
| `type` | Resource type. Only `Issue` is processed |
| `data.id` | Issue UUID — used to fingerprint and deduplicate all events from the same issue |
| `data.identifier` | Human-readable key (e.g., `ITO-5`) — shown in the alert title |
| `data.title` | Issue title — shown in the alert title |
| `data.priority` | Integer priority from Linear — used for priority mapping |
| `data.priorityLabel` | Human-readable priority (`Urgent`, `High`, etc.) |
| `data.state.type` | State category — `completed` and `canceled` trigger resolution |
| `data.state.name` | Human-readable state name (`Todo`, `In Progress`, `Done`) |
| `data.completedAt` | ISO 8601 timestamp set when the issue is completed |
| `data.url` | Direct link back to the issue in Linear |
| `data.team` | Team that owns the issue |
| `data.labels` | Labels attached to the issue |
| `data.assignee` | User assigned to the issue |
| `actor` | User or agent that triggered the event |
| `updatedFrom` | Previous values for fields that changed in this event (update events only) |
### Priority Mapping
Linear uses integer priority values. The platform maps them to internal priorities as follows:
| Linear `priority` | Linear Label | Platform Priority |
| ----------------- | ------------ | ----------------- |
| `1` | Urgent | CRITICAL |
| `2` | High | HIGH |
| `3` | Medium | MEDIUM |
| `4` | Low | LOW |
| `0` | No priority | MEDIUM (default) |
You control the issue priority in Linear. Changing an issue's priority after the alert is opened appends an update to the alert's timeline.
### RESOLVE Detection
The platform resolves an alert when Linear sends an update where the issue's `state.type` is `completed` (Done and custom done-category states) or `canceled`. It also resolves the alert when the issue is deleted (`action: remove`).
The resolve event is matched to the original alert using a fingerprint derived from the Linear issue's UUID (`data.id`), which is stable across the entire lifecycle of the issue. As long as the issue is not recreated, the fingerprint will match and the alert will be closed cleanly.
If the same issue is later reopened (moved from Done back to a non-completed state), the platform treats that as a new alert, since the previous alert is already resolved.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.itoc360.com/integrations/inbound-integrations/workflow-and-automation/linear-integration.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.