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

# Linear Webhook Setup Guide

> Configure Linear to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](https://docs.stackone.com/connectors/linear.md#getting-started) on the Linear connector page.

## Configure a Linear webhook

Linear delivers events to the StackOne **Native Webhook URL** once you create a webhook in your Linear workspace API settings. This works the same for **both authentication types** — a workspace admin creates the webhook manually in Linear whether your StackOne connection uses the **API Key** or **OAuth 2.0**. Inbound events are matched to the correct linked account automatically from the unique **Native Webhook URL** you register, so there is nothing extra to fill on the connection.

**1. Retrieve the Native Webhook URL from StackOne**

The **Native Webhook URL** is generated once an account has been linked. You will paste it into Linear in the next steps.

<ul>
  <li>Open the linked account in StackOne Hub.</li>
  <li>Copy the value from **Native Webhook URL**.</li>
</ul>

**2. Open the webhook settings in Linear**

Sign in to your [Linear account](https://linear.app) and open the API settings for your workspace. The **Webhooks** section is its own section on the API settings page — separate from **OAuth applications** and from your **Personal API keys** — so you create webhooks here regardless of whether your StackOne connection uses an API Key or OAuth.

<ul>
  <li>In the left sidebar under **Administration**, click **API**.</li>
  <li>In the **Webhooks** section, click **New webhook**.</li>
</ul>

![The API settings page with the Webhooks section and the New webhook button highlighted.](https://mintcdn.com/stackone-60/zJR_an0eNzF4PJ58/connectors/linear/images/events-open-webhooks.png?fit=max\&auto=format\&n=zJR_an0eNzF4PJ58\&q=85\&s=7224f01f45284e61b29ab338ef2b0f55)

**3. Add the label and webhook URL**

On the **Create webhook** page, identify the webhook and point it at StackOne.

<ul>
  <li>In **Label**, enter a descriptive name such as `StackOne Integration`.</li>
  <li>In **URL**, paste the **Native Webhook URL** you copied from StackOne.</li>
  <li>Linear auto-generates a **Signing secret** for the webhook. You do not need to copy it into StackOne — inbound events are authenticated by the token already embedded in the Native Webhook URL.</li>
</ul>

![The Create webhook form with the Label field set to StackOne Integration and the URL field highlighted.](https://mintcdn.com/stackone-60/zJR_an0eNzF4PJ58/connectors/linear/images/events-create-webhook.png?fit=max\&auto=format\&n=zJR_an0eNzF4PJ58\&q=85\&s=29d78ca18dc26acd0a3c27ebaca3e6b3)

**4. Select the events to subscribe to**

Under **Data change events** and **Other events**, enable the events you want delivered. Only the events you tick here are sent to StackOne.

<ul>
  <li>Tick each resource you want to receive, for example **Issues**, **Comments**, **Projects**, and **Cycles**.</li>
  <li>Enable **Issue SLA** under **Other events** to receive SLA events.</li>
  <li>See **Available webhook events** below for the full list and what each event covers.</li>
</ul>

![The Data change events and Other events checkboxes highlighted on the Create webhook form.](https://mintcdn.com/stackone-60/zJR_an0eNzF4PJ58/connectors/linear/images/events-select-events.png?fit=max\&auto=format\&n=zJR_an0eNzF4PJ58\&q=85\&s=a86f4f2ff60bb0ee10cf74f6bb5ed22f)

**5. Choose the team scope and create the webhook**

Decide which teams the webhook covers, then save it.

<ul>
  <li>In **Team selection**, choose **All public teams** to cover the whole workspace, or pick a single team. This cannot be changed after creation.</li>
  <li>Click **Create webhook**.</li>
</ul>

![The Team selection dropdown set to All public teams and the Create webhook button highlighted.](https://mintcdn.com/stackone-60/zJR_an0eNzF4PJ58/connectors/linear/images/events-team-create.png?fit=max\&auto=format\&n=zJR_an0eNzF4PJ58\&q=85\&s=7362d29a4141cc0dd2ae391603243c19)

## Available webhook events

The following Linear events can be enabled. Only events selected in Linear are delivered — Linear does not send events you have not subscribed to. Each event below shows the code StackOne routes on.

**1. Issue events**

Events related to issues. Enable the **Issues** checkbox.

<ul>
  <li>**Issue Created** (`Issue.create`) — Fired when a new issue is created.</li>
  <li>**Issue Updated** (`Issue.update`) — Fired when an issue changes, including status, assignee, or other field updates.</li>
  <li>**Issue Removed** (`Issue.remove`) — Fired when an issue is deleted.</li>
</ul>

**2. Issue label events**

Events related to issue labels. Enable the **Issue Labels** checkbox.

<ul>
  <li>**Issue Label Created** (`IssueLabel.create`) — Fired when a new issue label is created.</li>
  <li>**Issue Label Updated** (`IssueLabel.update`) — Fired when an issue label is renamed or recolored.</li>
  <li>**Issue Label Removed** (`IssueLabel.remove`) — Fired when an issue label is deleted.</li>
</ul>

**3. Issue attachment events**

Events related to attachments on issues. Enable the **Issue attachments** checkbox.

<ul>
  <li>**Attachment Created** (`Attachment.create`) — Fired when an attachment is added to an issue.</li>
  <li>**Attachment Updated** (`Attachment.update`) — Fired when an attachment on an issue changes.</li>
  <li>**Attachment Removed** (`Attachment.remove`) — Fired when an attachment is removed from an issue.</li>
</ul>

**4. Comment events**

Events related to issue comments. Enable the **Comments** checkbox.

<ul>
  <li>**Comment Created** (`Comment.create`) — Fired when a comment is added to an issue.</li>
  <li>**Comment Updated** (`Comment.update`) — Fired when an existing comment is edited.</li>
  <li>**Comment Removed** (`Comment.remove`) — Fired when a comment is deleted.</li>
</ul>

**5. Reaction events**

Events related to emoji reactions. Enable the **Emoji reactions** checkbox.

<ul>
  <li>**Reaction Created** (`Reaction.create`) — Fired when an emoji reaction is added.</li>
  <li>**Reaction Removed** (`Reaction.remove`) — Fired when an emoji reaction is removed.</li>
</ul>

**6. Project events**

Events related to projects. Enable the **Projects** checkbox.

<ul>
  <li>**Project Created** (`Project.create`) — Fired when a new project is created.</li>
  <li>**Project Updated** (`Project.update`) — Fired when a project changes.</li>
  <li>**Project Removed** (`Project.remove`) — Fired when a project is deleted.</li>
</ul>

**7. Project update events**

Events related to project status updates. Enable the **Project updates** checkbox.

<ul>
  <li>**Project Update Created** (`ProjectUpdate.create`) — Fired when a project update (status post) is created.</li>
  <li>**Project Update Updated** (`ProjectUpdate.update`) — Fired when a project update is edited.</li>
  <li>**Project Update Removed** (`ProjectUpdate.remove`) — Fired when a project update is deleted.</li>
</ul>

**8. Cycle events**

Events related to cycles. Enable the **Cycles** checkbox.

<ul>
  <li>**Cycle Created** (`Cycle.create`) — Fired when a new cycle is created.</li>
  <li>**Cycle Updated** (`Cycle.update`) — Fired when a cycle changes.</li>
  <li>**Cycle Removed** (`Cycle.remove`) — Fired when a cycle is deleted.</li>
</ul>

**9. Document events**

Events related to documents. Enable the **Documents** checkbox.

<ul>
  <li>**Document Created** (`Document.create`) — Fired when a new document is created.</li>
  <li>**Document Updated** (`Document.update`) — Fired when a document is edited.</li>
  <li>**Document Removed** (`Document.remove`) — Fired when a document is deleted.</li>
</ul>

**10. Initiative events**

Events related to initiatives. Enable the **Initiatives** checkbox.

<ul>
  <li>**Initiative Created** (`Initiative.create`) — Fired when a new initiative is created.</li>
  <li>**Initiative Updated** (`Initiative.update`) — Fired when an initiative changes.</li>
  <li>**Initiative Removed** (`Initiative.remove`) — Fired when an initiative is deleted.</li>
</ul>

**11. Initiative update events**

Events related to initiative status updates. Enable the **Initiative updates** checkbox.

<ul>
  <li>**Initiative Update Created** (`InitiativeUpdate.create`) — Fired when an initiative update is created.</li>
  <li>**Initiative Update Updated** (`InitiativeUpdate.update`) — Fired when an initiative update is edited.</li>
  <li>**Initiative Update Removed** (`InitiativeUpdate.remove`) — Fired when an initiative update is deleted.</li>
</ul>

**12. Customer events**

Events related to customers. Enable the **Customers** checkbox.

<ul>
  <li>**Customer Created** (`Customer.create`) — Fired when a new customer is created.</li>
  <li>**Customer Updated** (`Customer.update`) — Fired when a customer record changes.</li>
  <li>**Customer Removed** (`Customer.remove`) — Fired when a customer is deleted.</li>
</ul>

**13. Customer request events**

Events related to customer requests. Enable the **Customer requests** checkbox.

<ul>
  <li>**Customer Need Created** (`CustomerNeed.create`) — Fired when a customer request is created.</li>
  <li>**Customer Need Updated** (`CustomerNeed.update`) — Fired when a customer request changes.</li>
  <li>**Customer Need Removed** (`CustomerNeed.remove`) — Fired when a customer request is deleted.</li>
</ul>

**14. User events**

Events related to workspace users. Enable the **Users** checkbox.

<ul>
  <li>**User Updated** (`User.update`) — Fired when a workspace user's profile or membership changes.</li>
</ul>

**15. Issue SLA events**

SLA events for issues, under **Other events**. Enable the **Issue SLA** checkbox.

<ul>
  <li>**Issue SLA Created** (`IssueSLA.create`) — Fired when an SLA is set on an issue.</li>
  <li>**Issue SLA Updated** (`IssueSLA.update`) — Fired when an issue's SLA status changes, such as breaching or completing.</li>
  <li>**Issue SLA Removed** (`IssueSLA.remove`) — Fired when an SLA is removed from an issue.</li>
</ul>

**16. Audit log events**

Audit log entries are delivered through Linear's audit log webhook, which is configured separately from the data-change webhook above and may require an eligible Linear plan.

<ul>
  <li>**Audit Entry Created** (`AuditEntry.create`) — Fired when a new audit log entry is recorded in the workspace.</li>
</ul>

## Delivery format

How Linear delivers events to StackOne.

**1. One event per request**

Linear sends a separate HTTP POST for each event — payloads are not batched. Every request carries the event `type` (such as `Issue`) and `action` (`create`, `update`, or `remove`), which StackOne uses to route the event to its handler.

**2. Signature and retries**

Each request is signed with an HMAC-SHA256 **Linear-Signature** header and carries a **Linear-Timestamp**. Linear expects an HTTP 200 response within 5 seconds and retries failed deliveries up to 3 times with backoff; a webhook that keeps failing is disabled and must be re-enabled manually in Linear.

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.