# Linear webhooks

Linear webhooks are signed HTTP POST requests that tell your server when issues, comments, projects and other data change in a Linear workspace.

Agent skill: `npx skills add hookdeck/webhook-skills --skill linear-webhooks` ([details](https://hookdeck.com/webhooks/linear/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Linear's official docs](https://linear.app/developers/webhooks).

[Overview](https://hookdeck.com/webhooks/linear) · [Webhook events (23)](https://hookdeck.com/webhooks/linear/events) · [MCP events](https://hookdeck.com/webhooks/linear/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/linear/verify) · [Production guide](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/linear/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `Linear-Signature` Format: <hex> | [Linear docs](https://linear.app/developers/webhooks) |
| Scheme | `HMAC-SHA256` | [Linear docs](https://linear.app/developers/webhooks) |
| Signed material | `{raw body}` The request body as sent, with nothing added. webhookTimestamp is a field in that body, so the signature covers it. | [Linear docs](https://linear.app/developers/webhooks) |
| How events are identified | `Linear-Event header and action field in the body` | [Linear docs](https://linear.app/developers/webhooks) |
| Body format | `JSON` Content type: application/json. | [Linear docs](https://linear.app/developers/webhooks) |
| Replay window | `1 minutes` Linear recommends this check rather than enforcing it, so your handler makes it. Compare the body's `webhookTimestamp`, in Unix milliseconds, with your clock. | [Linear docs](https://linear.app/developers/webhooks) |
| Other headers | `linear-delivery, linear-event, linear-timestamp` | [Linear docs](https://linear.app/developers/webhooks) |
| Envelope | `action, type, actor, createdAt, data, url, updatedFrom, webhookTimestamp, webhookId, organizationId` | [Linear docs](https://linear.app/developers/webhooks) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill linear-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/linear/skill) |

[Verify Linear webhooks](https://hookdeck.com/webhooks/linear/verify)

## How Linear webhooks work

Webhooks push changes to your server as they happen, so you don't have to poll Linear's GraphQL API. When a resource type you subscribed to changes, Linear sends an HTTPS POST with a JSON body to your URL. A webhook belongs to an organization and covers one team or all public teams. For an OAuth app, Linear creates a webhook for each organization that authorizes it.

The `Linear-Event` header and the body's `type` name the entity, such as `Issue`, and `action` says what happened: `create`, `update` or `remove`. `data` holds the entity, and an `update` adds its previous values in `updatedFrom`. Other streams have their own actions and fields: `IssueSLA` sends `set`, `highRisk` or `breached` with `issueData`, and `AgentSessionEvent` sends `created` or `prompted` with `agentSession`.

## Setting up Linear webhooks

- Create a webhook under Settings, Administration, API with New webhook, or with the `webhookCreate` mutation, then choose its URL, label and resource types. It takes a workspace admin, or an OAuth app with the `admin` scope. OAuth apps set their webhook URL and categories in the app's own settings.
- Linear requires a public HTTPS URL that isn't localhost. To test on your machine, run `hookdeck listen 3000 linear --path /webhooks/linear` and use the URL the Hookdeck CLI prints.
- Linear's docs describe no way to resend a delivery, so log what you receive.
- Building an agent on these events? See [how to build a Linear agent](/webhooks/platforms/how-to-build-linear-agents-with-hookdeck-cli), or [how to run Claude Code as a Linear agent](/webhooks/platforms/how-to-run-claude-code-as-a-linear-agent-with-cyrus-and-hookdeck-cli).

## Delivery behaviour

- **Timeout:** 5 seconds. a slower response, or any status but 200, counts as a failure. [Guide](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** 3. after 1 minute, 1 hour and finally 6 hours. [Guide](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries:** may be disabled. if the URL stays unresponsive; re-enable it by hand. No resend is documented. [Guide](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** not documented. a retry can arrive hours after newer events. [Guide](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

1. **A 201 or 204 counts as a failure.** Linear treats any status other than 200 as a failed delivery and retries it. Return exactly 200 from your handler, within 5 seconds. [Respond in time](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts#timeouts)
2. **Duplicate deliveries.** A retry can repeat work your handler has already done. Record `Linear-Delivery`, and because Linear's docs don't say whether a retry reuses it, compare `data.id` and `data.updatedAt` too. [Handle duplicates](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts#duplicates)
3. **Out-of-order delivery.** Linear's docs make no promise about order, and a retry can arrive hours after newer events. Compare `data.updatedAt` with your stored value, and fetch from the GraphQL API when in doubt. [Handle ordering](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts#ordering)
4. **Webhook disabled after an outage.** After three retries, Linear might disable a webhook whose URL stays unresponsive, and it stays off until someone re-enables it. Its docs describe no resend, so reconcile from the GraphQL API. [Retries and disabled webhooks](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts#retries)

From [Hookdeck's Linear guide](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts).

## Linear webhook best practices

- **[Verify every signature and timestamp](https://hookdeck.com/webhooks/linear/verify).** Check `Linear-Signature` against the raw body, then reject a `webhookTimestamp` more than a minute from your clock.
- **[Return a 200 within 5 seconds](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts#timeouts).** Linear retries anything slower, and any other status code, so respond first and move the work to a queue.
- **[Make handlers idempotent](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts#duplicates).** A retry can repeat work you've already done, so record `Linear-Delivery` and check `data.id` and `data.updatedAt`.
- **[Don't let an older event win](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts#ordering).** Compare `data.updatedAt` with what you've stored, because a retry can arrive hours after newer events.
- **[Watch for a disabled webhook](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts#retries).** Linear may disable a webhook that stays unresponsive. Check its `enabled` field, and reconcile from the GraphQL API after an outage.
- **[Subscribe only to what you process](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts#choosing-events).** Pick the resource types and team you need, and check both `type` and `action` in your handler.

## Common Linear webhook events

### Issues

- [Issue](https://hookdeck.com/webhooks/linear/events#Issue): Issue created, updated or removed
- [Comment](https://hookdeck.com/webhooks/linear/events#Comment): Comment on an issue created, updated or removed
- [IssueLabel](https://hookdeck.com/webhooks/linear/events#IssueLabel): Issue label created, updated or removed
- [IssueSLA](https://hookdeck.com/webhooks/linear/events#IssueSLA): An issue's SLA is set, at high risk or breached

### Projects

- [Project](https://hookdeck.com/webhooks/linear/events#Project): Project created, updated or removed
- [ProjectUpdate](https://hookdeck.com/webhooks/linear/events#ProjectUpdate): Status update on a project created, updated or removed
- [Cycle](https://hookdeck.com/webhooks/linear/events#Cycle): Team cycle created, updated or removed

### Agents and OAuth apps

- [AgentSessionEvent](https://hookdeck.com/webhooks/linear/events#AgentSessionEvent): Your agent is mentioned, delegated an issue or sent a prompt
- [AppUserNotification](https://hookdeck.com/webhooks/linear/events#AppUserNotification): Inbox notification for your app's user, such as a mention
- [OAuthApp](https://hookdeck.com/webhooks/linear/events#OAuthApp): Your OAuth app is de-authorized from a workspace

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [project](https://hookdeck.com/webhooks/linear/events#resource-project) | 7 | 0 |
| [issue](https://hookdeck.com/webhooks/linear/events#resource-issue) | 6 | 1 |
| [app](https://hookdeck.com/webhooks/linear/events#resource-app) | 4 | 0 |

1 more resource. [All 23 events](https://hookdeck.com/webhooks/linear/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/linear/events): Every covered Linear event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/linear/mcp-events): How an agent subscribes to Linear events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/linear/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/linear/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/linear/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill linear-webhooks`
---

Not affiliated with Linear. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/linear.json) · [Report a correction](https://hookdeck.com/contact)
