Linear Webhooks & Events
Overview
Set up and handle Linear webhooks for real-time event processing. Linear sends HTTP POST requests for data changes on Issues, Comments, Issue Attachments, Documents, Emoji Reactions, Projects, Project Updates, Cycles, Labels, Users, and Issue SLAs.
Webhook headers:
Linear-Signature— HMAC-SHA256 hex digest of the raw bodyLinear-Delivery— Unique delivery ID for deduplicationLinear-Event— Event type (e.g., "Issue")Content-Type: application/json; charset=utf-8
Payload body includes: action, type, data, url, actor, updatedFrom (previous values on update), createdAt, webhookTimestamp (UNIX ms).
Prerequisites
- Linear workspace admin access (required for webhook creation)
- Public HTTPS endpoint for webhook delivery
- Webhook signing secret (generated in Linear Settings > API > Webhooks)
Instructions
Step 1: Build Webhook Receiver with Signature Verification
import express from "express";
import crypto from "crypto";
const app = express();
// CRITICAL: use raw body parser — JSON parsing destroys the original for signature verification
app.post("/webhooks/linear", express.raw({ type: "*/*" }), (req, res) => {
const signature = req.headers["linear-signature"] as string;
const delivery = req.headers["linear-delivery"] as string;
const eventType = req.headers["linear-event"] as string;
const rawBody = req.body.toString();
// 1. Verify HMAC-SHA256 signature
const expected = crypto
.createHmac("sha256", process.env.LINEAR_WEBHOOK_SECRET!)
.update(rawBody)
.digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
console.error(`Invalid signature for delivery ${delivery}`);
return res.status(401).json({ error: "Invalid signature" });
}
// 2. Parse and verify timestamp (guard against replay attacks)
const event = JSON.parse(rawBody);
const age = Date.now() - event.webhookTimestamp;
if (age > 60000) {
return res.status(400).json({ error: "Webhook expired" });
}
// 3. Respond 200 immediately, process asynchronously
res.json({ received: true });
processEvent(event, delivery).catch(err =>
console.error(`Failed processing ${delivery}:`, err)
);
});
app.listen(3000, () => console.log("Webhook server on :3000"));
Step 2: Event Type Definition
interface LinearWebhookPayload {
action: "create" | "update" | "remove";
type: string; // "Issue", "Comment", "Project", "Cycle", "IssueLabel", etc.
data: Record<string, any>;
url: string;
actor?: {
id: string;
type: string; // "user", "application"
name?: string;
};
updatedFrom?: Record<string, any>; // Only contains fields that changed
createdAt: string;
webhookTimestamp: number;
}
Step 3: Event Router
type Handler = (event: LinearWebhookPayload) => Promise<void>;
const handlers: Record<string, Record<string, Handler>> = {
Issue: {
create: async (e) => {
console.log(`New issue: ${e.data.identifier} — ${e.data.title}`);
console.log(` Priority: ${e.data.priority}, Team: ${e.data.team?.key}`);
// e.g., notify Slack, sync to external system
},
update: async (e) => {
// updatedFrom contains ONLY the fields that changed
if (e.updatedFrom?.stateId) {
console.log(`${e.data.identifier} state -> ${e.data.state?.name}`);
if (e.data.state?.type === "completed") {
await notifySlack(`Done: ${e.data.identifier} ${e.data.title}`);
}
}
if (e.updatedFrom?.assigneeId) {
console.log(`${e.data.identifier} assigned to ${e.data.assignee?.name}`);
}
if (e.updatedFrom?.priority !== undefined) {
console.log(`${e.data.identifier} priority changed to ${e.data.priority}`);
}
},
remove: async (e) => {
console.log(`Issue deleted: ${e.data.identifier}`);
},
},
Comment: {
create: async (e) => {
console.log(`Comment on ${e.data.issue?.identifier}: ${e.data.body?.substring(0, 100)}`);
},
},
Project: {
update: async (e) => {
if (e.updatedFrom?.state) {
console.log(`Project "${e.data.name}" -> ${e.data.state}`);
}
},
},
Cycle: {
update: async (e) => {
if (e.updatedFrom?.completedAt && e.data.completedAt) {
console.log(`Cycle "${e.data.name}" completed`);
}
},
},
ProjectUpdate: {
create: async (e) => {
// e.data includes diffMarkdown showing changes since last update
console.log(`Project update: ${e.data.body?.substring(0, 100)}`);
},
},
};
async function processEvent(event: LinearWebhookPayload, deliveryId: string): Promise<void> {
const handler = handlers[event.type]?.[event.action];
if (handler) {
await handler(event);
} else {
console.log(`Unhandled: ${event.type}.${event.action} (delivery: ${deliveryId})`);
}
}
Step 4: Idempotent Processing
Linear may retry failed deliveries. Deduplicate using the Linear-Delivery header.
// In-memory for simple apps; use Redis/DB for distributed systems
const processedDeliveries = new Set<string>();
const MAX_TRACKED = 10000;
function isDuplicate(deliveryId: string): boolean {
if (processedDeliveries.has(deliveryId)) return true;
processedDeliveries.add(deliveryId);
if (processedDeliveries.size > MAX_TRACKED) {
const entries = [...processedDeliveries];
entries.slice(0, MAX_TRACKED / 2).forEach(id => processedDeliveries.delete(id));
}
return false;
}
// In webhook handler, after signature verification:
if (isDuplicate(delivery)) {
return res.json({ status: "duplicate, skipped" });
}
Step 5: Register Webhook
# Via Linear UI:
# Settings > API > Webhooks > New webhook
# URL: https://your-app.com/webhooks/linear
# Resource types: Issues, Comments, Projects, Cycles
# Teams: All public teams (or select specific ones)
# Via GraphQL API:
curl -X POST https://api.linear.app/graphql \
-H "Authorization: $LINEAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "mutation { webhookCreate(input: { url: \"https://your-app.com/webhooks/linear\", resourceTypes: [\"Issue\", \"Comment\", \"Project\", \"Cycle\"], allPublicTeams: true }) { success webhook { id enabled secret } } }"
}'
Step 6: List and Manage Webhooks via SDK
import { LinearClient } from "@linear/sdk";
const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY! });
// List all webhooks
const webhooks = await client.webhooks();
for (const wh of webhooks.nodes) {
console.log(`${wh.url} — enabled: ${wh.enabled}, types: ${wh.resourceTypes?.join(", ")}`);
}
// Disable a webhook
await client.updateWebhook("webhook-id", { enabled: false });
// Delete a webhook
await client.deleteWebhook("webhook-id");
Step 7: Local Development with ngrok
# Terminal 1: Start webhook server
npm run dev
# Terminal 2: Expose port 3000
ngrok http 3000
# Copy the https://xxxx.ngrok-free.app URL
# Register in Linear Settings > API > Webhooks > New webhook
# URL: https://xxxx.ngrok-free.app/webhooks/linear
Error Handling
| Error | Cause | Solution |
|-------|-------|----------|
| 401 Invalid signature | Wrong secret or body parsed as JSON | Use express.raw(), verify secret matches Linear |
| Webhook not received | URL not publicly accessible | Check HTTPS, firewall rules, ngrok tunnel |
| Duplicate processing | Linear retried delivery | Deduplicate using Linear-Delivery header |
| Handler timeout | Processing takes too long | Respond 200 immediately, process async |
| Missing updatedFrom | Field didn't change | updatedFrom only contains changed field keys |
| actor is null | System-triggered event | Check actor.type before accessing .name |
Examples
Slack Notification on Issue Completion
async function notifySlack(message: string) {
await fetch(process.env.SLACK_WEBHOOK_URL!, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ text: message }),
});
}
// In Issue.update handler:
if (e.updatedFrom?.stateId && e.data.state?.type === "completed") {
await notifySlack(
`*${e.data.identifier}* completed by ${e.actor?.name ?? "system"}\n${e.data.title}`
);
}