Linear Integration

Overview

Linear 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

{
  "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:

{
  "action": "create",
  "actor": {
    "id": "1cbbf81a-29db-4874-87b3-e1d0c64dd8b9",
    "name": "[email protected]",
    "email": "[email protected]",
    "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:

{
  "action": "update",
  "actor": {
    "id": "1cbbf81a-29db-4874-87b3-e1d0c64dd8b9",
    "name": "[email protected]",
    "email": "[email protected]",
    "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.