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.

23 events covered

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.

Key facts

Signature header
Linear-Signature

Format: <hex>

Scheme
HMAC-SHA256
Signed material
{raw body}

The request body as sent, with nothing added. webhookTimestamp is a field in that body, so the signature covers it.

How events are identified
Linear-Event header and action field in the body
Body format
JSON

Content type: application/json.

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.

Other headers
linear-delivery, linear-event, linear-timestamp
Envelope
action, type, actor, createdAt, data, url, updatedFrom, webhookTimestamp, webhookId, organizationId
Agent skill
npx skills add hookdeck/webhook-skills --skill linear-webhooks

Verify Linear webhooks →

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, or how to run Claude Code as a Linear agent.

Delivery behaviour

  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 →
  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 →
  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 →
  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 →

Linear webhook best practices

Common Linear webhook events

Issues

Issue Issue created, updated or removed
Comment Comment on an issue created, updated or removed
IssueLabel Issue label created, updated or removed
IssueSLA An issue's SLA is set, at high risk or breached

Projects

Project Project created, updated or removed
ProjectUpdate Status update on a project created, updated or removed
Cycle Team cycle created, updated or removed

Agents and OAuth apps

AgentSessionEvent Your agent is mentioned, delegated an issue or sent a prompt
AppUserNotification Inbox notification for your app's user, such as a mention
OAuthApp Your OAuth app is de-authorized from a workspace

Events by resource

Resource Events Payloads
project

Project · ProjectUpdate · ProjectLabel · Cycle +3

7 0
issue

Issue · Comment · IssueLabel · Attachment +2

6 1
app

OAuthApp · AgentSessionEvent · AppUserNotification · PermissionChange

4 0

1 more resource, including Other Linear events. All 23 events →

In this hub

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

Keep a slow handler from getting your Linear webhook disabled.

Hookdeck Event Gateway accepts every Linear delivery, verifies its signature, queues events and retries to your service on your schedule.

Not affiliated with Linear. Facts are compiled from public sources and linked inline.