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.
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
{raw body} The request body as sent, with nothing added. webhookTimestamp is a field in that body, so the signature covers it.
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.
action, type, actor, createdAt, data, url, updatedFrom, webhookTimestamp, webhookId, organizationId Setting up Linear webhooks
- Create a webhook under Settings, Administration, API with New webhook, or with the
webhookCreatemutation, then choose its URL, label and resource types. It takes a workspace admin, or an OAuth app with theadminscope. 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/linearand 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
5 seconds a slower response, or any status but 200, counts as a failure Retries 3 after 1 minute, 1 hour and finally 6 hours After retries may be disabled if the URL stays unresponsive; re-enable it by hand. No resend is documented Ordering not documented a retry can arrive hours after newer events Known failure modes
From Hookdeck's Linear guide →-
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 → -
Duplicate deliveries
A retry can repeat work your handler has already done. Record
Handle duplicates →Linear-Delivery, and because Linear's docs don't say whether a retry reuses it, comparedata.idanddata.updatedAttoo. -
Out-of-order delivery
Linear's docs make no promise about order, and a retry can arrive hours after newer events. Compare
Handle ordering →data.updatedAtwith your stored value, and fetch from the GraphQL API when in doubt. -
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
- Verify every signature and timestamp.
Check
Linear-Signatureagainst the raw body, then reject awebhookTimestampmore than a minute from your clock. - Return a 200 within 5 seconds. Linear retries anything slower, and any other status code, so respond first and move the work to a queue.
- Make handlers idempotent.
A retry can repeat work you've already done, so record
Linear-Deliveryand checkdata.idanddata.updatedAt. - Don't let an older event win.
Compare
data.updatedAtwith what you've stored, because a retry can arrive hours after newer events. - Watch for a disabled webhook.
Linear may disable a webhook that stays unresponsive. Check its
enabledfield, and reconcile from the GraphQL API after an outage. - Subscribe only to what you process.
Pick the resource types and team you need, and check both
typeandactionin your handler.
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 | 7 | 0 |
issue | 6 | 1 |
app | 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.