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();
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();
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" });
}
const event = JSON.parse(rawBody);
const age = Date.now() - event.webhookTimestamp;
if (age > 60000) {
return res.status(400).json({ error: "Webhook expired" });
}
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;
data: Record<string, any>;
url: string;
actor?: {
id: string;
type: string;
name?: string;
};
updatedFrom?: Record<string, any>;
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}`);
},
update: async (e) => {
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}`);
}
}
(e.?.) {
.();
}
(e.?. !== ) {
.();
}
},
: (e) => {
.();
},
},
: {
: (e) => {
.();
},
},
: {
: (e) => {
(e.?.) {
.();
}
},
},
: {
: (e) => {
(e.?. && e..) {
.();
}
},
},
: {
: (e) => {
.();
},
},
};
(): <> {
handler = handlers[event.]?.[event.];
(handler) {
(event);
} {
.();
}
}
Step 4: Idempotent Processing
Linear may retry failed deliveries. Deduplicate using the Linear-Delivery header.
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;
}
if (isDuplicate(delivery)) {
return res.json({ status: "duplicate, skipped" });
}
Step 5: Register Webhook
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! });
const webhooks = await client.webhooks();
for (const wh of webhooks.nodes) {
console.log(`${wh.url} — enabled: ${wh.enabled}, types: ${wh.resourceTypes?.join(", ")}`);
}
await client.updateWebhook("webhook-id", { enabled: false });
await client.deleteWebhook("webhook-id");
Step 7: Local Development with ngrok
npm run dev
ngrok http 3000
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 }),
});
}
if (e.updatedFrom?.stateId && e.data.state?.type === "completed") {
await notifySlack(
`*${e.data.identifier}* completed by ${e.actor?.name ?? "system"}\n${e.data.title}`
);
}
Resources
