Configure and handle Linear webhooks for real-time event processing. Use when setting up webhooks, handling Linear events, or building real-time integrations. Trigger with phrases like "linear webhooks", "linear events", "linear real-time", "handle linear webhook", "linear webhook setup".
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill linear-webhooks-eventsLoading…
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-8Payload body includes: action, type, data, url, , (previous values on update), , (UNIX ms).
actorupdatedFromcreatedAtwebhookTimestampimport 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"));
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;
}
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})`);
}
}
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" });
}
# 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 } } }"
}'
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");
# 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 | 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 |
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}`
);
}
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).