Linear Migration Deep Dive

Overview

Comprehensive guide for migrating from Jira, Asana, or GitHub Issues to Linear. Covers assessment, workflow mapping, data export, transformation, batch import with hierarchy support, and post-migration validation. Linear also has a built-in importer (Settings > Import) for Jira, Asana, GitHub, and CSV.

Prerequisites

• Admin access to source system (Jira/Asana/GitHub)
• Linear workspace with admin access
• API keys for both source and Linear
• Migration timeline and rollback plan

Instructions

Step 1: Migration Assessment Checklist

Data Volume
[ ] Total issues/tasks: ___
[ ] Projects/boards: ___
[ ] Users to map: ___
[ ] Attachments: ___
[ ] Custom fields: ___
[ ] Comments: ___

Workflow Analysis
[ ] Source statuses documented
[ ] Status-to-state mapping defined
[ ] Priority mapping defined
[ ] Issue type-to-label mapping defined
[ ] Automations to recreate: ___

Timeline
[ ] Migration window: ___
[ ] Parallel run period: ___
[ ] Cutover date: ___
[ ] Rollback deadline: ___

Step 2: Workflow Mapping

Jira -> Linear:

Asana -> Linear:

Step 3: Export from Source System

Jira Export:

// src/migration/jira-exporter.ts
interface JiraIssue {
  key: string;
  summary: string;
  description: string;
  status: string;
  priority: string;
  issuetype: string;

Linear Multi-Environment Setup

Overview

Configure Linear integrations across dev, staging, and production with isolated API keys, secret management, environment guards, and per-environment webhook routing. Use separate Linear workspaces or at minimum separate API keys per environment.

Prerequisites

• Separate Linear API keys per environment (dev, staging, prod)
• Secret management (Vault, AWS Secrets Manager, GCP Secret Manager)
• CI/CD pipeline with environment support
• Node.js 18+

Instructions

Step 1: Environment Configuration

// src/config/linear.ts
import { LinearClient } from "@linear/sdk";

interface LinearEnvConfig {
  apiKey: string;
  webhookSecret: string;
  defaultTeamKey: string;
  enableWebhooks: boolean;
  enableDebugLogging: boolean;
  cacheEnabled: boolean;
}

type Environment = "development" | "staging" | "production" | "test";

function getEnvironment(): Environment {
  const env = process.env.NODE_ENV ?? "development";
  if (!["development", "staging", "production", "test"].includes(env)) {
    throw new Error(`Unknown NODE_ENV: ${env}`);
  }
  return env as Environment;
}

async function loadConfig(): Promise<LinearEnvConfig> {
  const env = getEnvironment();

  // In production, use secret manager instead of env vars
  if (env === "production" || env === "staging") {
    return {
      apiKey: await getSecret(`linear-api-key-${env}`),
      webhookSecret: await getSecret(`linear-webhook-secret-${env}`),
      defaultTeamKey: process.env.LINEAR_DEFAULT_TEAM_KEY ?? "ENG",
      enableWebhooks: true,
      enableDebugLogging: env === "staging",
      cacheEnabled: true,
    };
  }

  // Dev/test: use environment variables
  return {
    apiKey: process.env.LINEAR_API_KEY ?? "",
    webhookSecret: process.env.LINEAR_WEBHOOK_SECRET ?? "",
    defaultTeamKey: process.env.LINEAR_DEV_TEAM_KEY ?? "DEV",
    enableWebhooks: false, // No webhook server in local dev
    enableDebugLogging: true,
    cacheEnabled: false,
  };
}

Step 2: Secret Manager Integration

// GCP Secret Manager
import { SecretManagerServiceClient } from "@google-cloud/secret-manager";

async function getSecret(name: string): Promise<string> {
  const client = new SecretManagerServiceClient();
  const projectId = process.env.GCP_PROJECT_ID!;
  const [version] = await client.accessSecretVersion({
    name: `projects/${projectId}/secrets/${name}/versions/latest`,
  });
  return version.payload?.data?.toString() ?? "";
}

// AWS Secrets Manager
import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";

async function getSecretAWS(name: string):

Linear Observability

Overview

Production monitoring for Linear integrations using Prometheus metrics, structured logging with pino, health checks, and alerting rules. Track API latency, error rates, rate limit headroom, and webhook throughput.

Prerequisites

• Linear integration deployed
• Prometheus or Datadog for metrics
• Structured logging (pino, winston)
• Alerting system (PagerDuty, OpsGenie, Slack)

Instructions

Step 1: Define Metrics

// src/metrics/linear-metrics.ts
import { Counter, Histogram, Gauge, register } from "prom-client";

export const metrics = {
  // API request tracking
  apiRequests: new Counter({
    name: "linear_api_requests_total",
    help: "Total Linear API requests",
    labelNames: ["operation", "status"],
  }),

  // Request duration
  apiLatency: new Histogram({
    name: "linear_api_request_duration_seconds",
    help: "Linear API request duration",
    labelNames: ["operation"],
    buckets: [0.1, 0.25, 0.5, 1, 2, 5, 10],
  }),

  // Rate limit headroom
  rateLimitRemaining: new Gauge({
    name: "linear_rate_limit_remaining",
    help: "Remaining rate limit budget",
    labelNames: ["type"], // "requests" or "complexity"
  }),

  // Webhook tracking
  webhooksReceived: new Counter({
    name: "linear_webhooks_received_total",
    help: "Total webhooks received",
    labelNames: ["type", "action"],
  }),

  webhookProcessingDuration: new Histogram({
    name: "linear_webhook_processing_seconds",
    help: "Webhook processing duration",
    labelNames: ["type"],
    buckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
  }),

  // Cache effectiveness
  cacheHits: new Counter({
    name: "linear_cache_hits_total",
    help: "Cache hit count",
    labelNames: ["key"],
  }),
  cacheMisses: new Counter({
    name: "linear_cache_misses_total",
    help: "Cache miss count",
    labelNames: ["key"],
  }),
};

// Expose metrics endpoint
app.get("/metrics", async (req, res) => {
  res.set("Content-Type", register.contentType);
  res.end(await register.metrics());
});

Step 2: Instrumented Client Wrapper

import { LinearClient } from "@linear/sdk";

function instrumentedCall<T>(
  operation: string,
  fn: () => Promise<T>
): Promise<T> {
  const timer = metrics.apiLatency.startTimer({ operation });

  return fn()
    .then((result) => {
      metrics.apiRequests.inc({ operation, status: "success" });
      timer();
      return result;
    })
    .catch((error: any) => {
      const status = error.status === 429 ? "rate_limited"

Linear Performance Tuning

Overview

Optimize Linear API usage for minimal latency and efficient resource consumption. The three main levers are: (1) query flattening to avoid N+1 and reduce complexity, (2) caching static data with webhook-driven invalidation, and (3) batching mutations into single GraphQL requests.

Key numbers:

• Query complexity budget: 250,000 pts/hour, max 10,000 per query
• Each property: 0.1 pt, each object: 1 pt, connections: multiply by first
• Best practice: sort by updatedAt to get fresh data first

Prerequisites

• Working Linear integration with @linear/sdk
• Understanding of GraphQL query structure
• Optional: Redis for distributed caching

Instructions

Step 1: Eliminate N+1 Queries

The SDK lazy-loads relations. Accessing .assignee on 50 issues makes 50 separate API calls.

import { LinearClient } from "@linear/sdk";

const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY! });

// BAD: N+1 — 1 query for issues + 50 for assignees + 50 for states = 101 requests
const issues = await client.issues({ first: 50 });
for (const i of issues.nodes) {
  const assignee = await i.assignee;  // API call!
  const state = await i.state;        // API call!
  console.log(`${i.identifier}: ${assignee?.name} [${state?.name}]`);
}

// GOOD: 1 request — use rawRequest with exact field selection
const response = await client.client.rawRequest(`
  query TeamDashboard($teamId: String!) {
    team(id: $teamId) {
      issues(first: 50, orderBy: updatedAt) {
        nodes {
          id identifier title priority estimate updatedAt
          assignee { name email }
          state { name type }
          labels { nodes { name color } }
          project { name }
        }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
`, { teamId: "team-uuid" });
// Complexity: ~50 * (10 fields * 0.1 + 4 objects) = ~275 pts

Step 2: Cache Static Data

Teams, workflow states, and labels change rarely. Cache them with appropriate TTLs.

interface CacheEntry<T> {
  data: T;
  expiresAt: number;
}

class LinearCache {
  private store = new Map<string, CacheEntry<any>>();

  get<T>(key: string): T | null {
    const entry = this.store.get(key);
    if (!entry || Date.now() > entry.expiresAt) {
      this.store.delete(key);
      return null;
    }
    return entry.data;
  }

  set<T>(key: string, data: T, ttlSeconds: number): void {
    this.store.set(key, { data, expiresAt: Date.now() + ttlSeconds * 1000 });
  }

  invalidate(key: string): void {
    this.store.delete(key);
  }
}

const cache = new LinearCache();

// Teams: 10 minute TTL (almost never change)
async function getTeams(client: LinearCli

Linear Production Checklist

Overview

Comprehensive checklist and implementation patterns for deploying Linear integrations to production. Covers authentication, error handling, rate limiting, monitoring, data handling, and deployment verification.

Prerequisites

• Working development integration passing all tests
• Production Linear workspace (or production API key)
• Deployment infrastructure (Vercel, Cloud Run, etc.)
• Secret management solution (not .env files in production)

Pre-Production Checklist

1. Authentication & Security

[ ] Production API key generated (separate from dev)
[ ] API key stored in secret manager (Vault, AWS SM, GCP SM)
[ ] OAuth redirect URIs updated for production domain
[ ] Webhook secrets are unique per environment
[ ] All dev secrets rotated before launch
[ ] HTTPS enforced on all endpoints
[ ] Webhook HMAC-SHA256 verification implemented
[ ] Webhook timestamp validation (< 60s age)
[ ] Token refresh flow implemented (mandatory since Oct 2025)

2. Error Handling & Resilience

[ ] All Linear API calls wrapped in try/catch
[ ] Rate limit retry with exponential backoff (max 5 retries)
[ ] 30s timeout on all API calls
[ ] Graceful degradation when Linear API is down
[ ] Error logging includes context (no secrets in logs)
[ ] InvalidInputLinearError caught separately from network errors
[ ] Alerts configured for auth failures and error rate spikes

3. Performance & Rate Limits

[ ] Pagination with first:50 for all list queries
[ ] Caching for static data (teams, states, labels) — 10-30 min TTL
[ ] Request batching for bulk operations (20 mutations per batch)
[ ] Query complexity stays under 5,000 pts per request
[ ] No polling — webhooks for real-time updates
[ ] N+1 query patterns eliminated (use rawRequest for joins)
[ ] Response times monitored with p95 alerting

4. Monitoring & Observability

[ ] Health check endpoint hitting Linear API
[ ] API latency metrics collected per operation
[ ] Error rate monitoring with alerting (>1% = alert)
[ ] Rate limit remaining tracked (alert if < 100 requests)
[ ] Structured JSON logging for API calls and webhooks
[ ] Webhook delivery tracking via Linear-Delivery header

5. Data Handling

[ ] No PII logged or stored unnecessarily
[ ] Webhook event idempotency (deduplicate by Linear-Delivery)
[ ] Data retention policy defined for synced data
[ ] Stale data detection with periodic consistency checks

Production Configuration

import { LinearClient } from "@linear/sdk";

interface ProdConfig {
  linear: { apiKey: string; webhookSecret: string };
  rateLimit: { maxRetries: number; baseDelayMs: number; maxDelayMs: number };
  cache: { teamsTtl: number; states

Linear Rate Limits

Overview

Linear uses the leaky bucket algorithm with two rate limiting dimensions. Understanding both is critical for reliable integrations:

Complexity scoring: Each property = 0.1 pt, each object = 1 pt, connections multiply children by first arg (default 50), then round up.

Prerequisites

• @linear/sdk installed
• Understanding of HTTP response headers
• Familiarity with async/await patterns

Instructions

Step 1: Read Rate Limit Headers

Linear returns rate limit info on every response.

const response = await fetch("https://api.linear.app/graphql", {
  method: "POST",
  headers: {
    Authorization: process.env.LINEAR_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "{ viewer { id } }" }),
});

// Key headers
const headers = {
  requestsRemaining: response.headers.get("x-ratelimit-requests-remaining"),
  requestsLimit: response.headers.get("x-ratelimit-requests-limit"),
  requestsReset: response.headers.get("x-ratelimit-requests-reset"),
  complexityRemaining: response.headers.get("x-ratelimit-complexity-remaining"),
  complexityLimit: response.headers.get("x-ratelimit-complexity-limit"),
  queryComplexity: response.headers.get("x-complexity"),
};

console.log(`Requests: ${headers.requestsRemaining}/${headers.requestsLimit}`);
console.log(`Complexity: ${headers.complexityRemaining}/${headers.complexityLimit}`);
console.log(`This query cost: ${headers.queryComplexity} points`);

Step 2: Exponential Backoff with Jitter

import { LinearClient } from "@linear/sdk";

class RateLimitedClient {
  private client: LinearClient;

  constructor(apiKey: string) {
    this.client = new LinearClient({ apiKey });
  }

  async withRetry<T>(fn: () => Promise<T>, maxRetries = 5): Promise<T> {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
      try {
        return await fn();
      } catch (error: any) {
        const isRateLimited = error.status === 429 ||
          error.message?.includes("rate") ||
          error.type === "ratelimited";

        if (!isRateLimited || attempt === maxRetries - 1) throw error;

        // Exponential backoff: 1s, 2s, 4s,

Linear Reference Architecture

Overview

Production-grade architectural patterns for Linear integrations. Choose the right pattern based on team size, complexity, and real-time requirements.

Architecture Decision Matrix

Architecture 1: Simple Integration

Direct SDK calls from your application. Best for scripts, internal tools, and prototypes.

// src/linear.ts — single module, shared client
import { LinearClient } from "@linear/sdk";

const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY! });

// Direct SDK calls from any part of your app
export async function getOpenIssues(teamKey: string) {
  return client.issues({
    first: 50,
    filter: {
      team: { key: { eq: teamKey } },
      state: { type: { nin: ["completed", "canceled"] } },
    },
    orderBy: "priority",
  });
}

export async function createBugReport(teamId: string, title: string, description: string) {
  const labels = await client.issueLabels({ filter: { name: { eq: "Bug" } } });
  return client.createIssue({
    teamId,
    title,
    description,
    priority: 2,
    labelIds: labels.nodes.length ? [labels.nodes[0].id] : [],
  });
}

Architecture 2: Service-Oriented with Gateway

Centralized Linear access through a gateway service with caching and rate limiting.

// src/linear-gateway.ts
import { LinearClient } from "@linear/sdk";

class LinearGateway {
  private client: LinearClient;
  private cache = new Map<string, { data: any; expiresAt: number }>();
  private requestQueue: Array<{ fn: () => Promise<any>; resolve: Function; reject: Function }> = [];
  private processing = false;

  constructor(apiKey: string) {
    this.client = new LinearClient({ apiKey });
  }

  // Cached reads
  async getTeams() {
    return this.cachedQuery("teams", () => this.client.teams().then(r => r.nodes), 600);
  }

  async getStates(teamId: string) {
    return this.cachedQuery(`states:${teamId}`, async () => {
      const team = await this.client.team(teamId);
      return (await team.states()).nodes;
    }, 1800)

Linear SDK Patterns

Overview

Production patterns for @linear/sdk. The SDK wraps Linear's GraphQL API with strongly-typed models, cursor-based pagination (fetchNext()/fetchPrevious()), lazy-loaded relations, and typed error classes. Understanding these patterns avoids N+1 queries and rate limit waste.

Prerequisites

• @linear/sdk installed
• TypeScript project with strict: true
• Understanding of async/await and GraphQL concepts

Instructions

Pattern 1: Client Singleton

import { LinearClient } from "@linear/sdk";

let _client: LinearClient | null = null;

export function getLinearClient(): LinearClient {
  if (!_client) {
    const apiKey = process.env.LINEAR_API_KEY;
    if (!apiKey) throw new Error("LINEAR_API_KEY is required");
    _client = new LinearClient({ apiKey });
  }
  return _client;
}

// For multi-user OAuth apps — one client per user
const clientCache = new Map<string, LinearClient>();

export function getClientForUser(userId: string, accessToken: string): LinearClient {
  if (!clientCache.has(userId)) {
    clientCache.set(userId, new LinearClient({ accessToken }));
  }
  return clientCache.get(userId)!;
}

Pattern 2: Cursor-Based Pagination

Linear uses Relay-style cursor pagination. The SDK provides fetchNext() and fetchPrevious() helpers, plus raw pageInfo for manual control.

// SDK built-in pagination helpers
const firstPage = await client.issues({ first: 50 });
console.log(`Page 1: ${firstPage.nodes.length} issues`);

if (firstPage.pageInfo.hasNextPage) {
  const secondPage = await firstPage.fetchNext();
  console.log(`Page 2: ${secondPage.nodes.length} issues`);
}

// Manual pagination with cursor — good for streaming all data
async function* paginateAll<T>(
  fetchPage: (cursor?: string) => Promise<{
    nodes: T[];
    pageInfo: { hasNextPage: boolean; endCursor: string };
  }>
): AsyncGenerator<T> {
  let cursor: string | undefined;
  let hasNext = true;

  while (hasNext) {
    const page = await fetchPage(cursor);
    for (const node of page.nodes) yield node;
    hasNext = page.pageInfo.hasNextPage;
    cursor = page.pageInfo.endCursor;
  }
}

// Stream all issues without loading everything into memory
for await (const issue of paginateAll(c => client.issues({ first: 50, after: c }))) {
  console.log(`${issue.identifier}: ${issue.title}`);
}

Pattern 3: Relation Loading (Avoiding N+1)

SDK models lazy-load relations. Accessing .assignee triggers a separate API call. Use raw GraphQL to batch-fetch relations in one request.

// LAZY (N+1 problem) — each .assignee is a separate API call
const issues = await client.iss

Linear Security Basics

Overview

Secure authentication patterns for Linear integrations: API key management, OAuth 2.0 with PKCE, token refresh (mandatory for new apps after Oct 2025), webhook HMAC-SHA256 signature verification, and secret rotation.

Prerequisites

• Linear account with API access
• Understanding of environment variables and secret management
• Familiarity with OAuth 2.0 and HMAC concepts

Instructions

Step 1: Secure API Key Storage

// NEVER hardcode keys
// BAD:
// const client = new LinearClient({ apiKey: "lin_api_xxxx" });

// GOOD: environment variable
import { LinearClient } from "@linear/sdk";

const client = new LinearClient({
  apiKey: process.env.LINEAR_API_KEY!,
});

Environment setup:

# .env (never commit)
LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
LINEAR_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx

# .gitignore
.env
.env.*
!.env.example

# .env.example (commit for documentation)
LINEAR_API_KEY=lin_api_your_key_here
LINEAR_WEBHOOK_SECRET=your_webhook_secret_here

Startup validation:

function validateConfig(): void {
  const key = process.env.LINEAR_API_KEY;
  if (!key) throw new Error("LINEAR_API_KEY is required");
  if (!key.startsWith("lin_api_")) throw new Error("LINEAR_API_KEY has invalid format");
  if (key.length < 30) throw new Error("LINEAR_API_KEY appears truncated");
}
validateConfig();

Step 2: OAuth 2.0 with PKCE

import express from "express";
import crypto from "crypto";

const app = express();

const OAUTH = {
  clientId: process.env.LINEAR_CLIENT_ID!,
  clientSecret: process.env.LINEAR_CLIENT_SECRET!,
  redirectUri: process.env.LINEAR_REDIRECT_URI!,
  scopes: ["read", "write", "issues:create"],
};

// Generate PKCE verifier and challenge
function generatePKCE() {
  const verifier = crypto.randomBytes(32).toString("base64url");
  const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
  return { verifier, challenge };
}

// Step 1: Redirect to Linear authorization
app.get("/auth/linear", (req, res) => {
  const state = crypto.randomBytes(16).toString("hex");
  const { verifier, challenge } = generatePKCE();

  // Store state + verifier in session
  req.session!.oauthState = state;
  req.session!.codeVerifier = verifier;

  const url = new URL("https://linear.app/oauth/authorize");
  url.searchParams.set("client_id", OAUTH.clientId);
  url.searchParams.set("redirect_uri", OAUTH.redirectUri);
  url.searchParams.set("response_type", "code");
  url.searchParams.set(&

Linear Upgrade Migration

Overview

Safely upgrade @linear/sdk versions with zero downtime. The SDK is auto-generated from Linear's GraphQL schema -- major versions can rename fields, change return types, add required parameters, or remove deprecated methods. This skill covers version checking, upgrade procedure, compatibility layers, and rollback.

Prerequisites

• Existing Linear integration with version control (Git)
• Test suite covering Linear SDK operations
• Understanding of semantic versioning

Instructions

Step 1: Check Current vs Latest Version

set -euo pipefail
# Current installed version
npm list @linear/sdk 2>/dev/null || echo "Not installed"

# Latest available
npm view @linear/sdk version

# All recent versions
npm view @linear/sdk versions --json | jq '.[-10:]'

Step 2: Review Changelog for Breaking Changes

set -euo pipefail
# View SDK changelog on GitHub
npm view @linear/sdk repository.url
# Then check: https://github.com/linear/linear/blob/master/packages/sdk/CHANGELOG.md

# Also review Linear's API changelog:
# https://linear.app/changelog (filter for API/developer updates)

Common breaking changes between major versions:

• Renamed fields: e.g., issue.state property vs lazy relation
• Changed return types: direct value to paginated connection
• New required parameters: mutations gaining mandatory fields
• Removed methods: deprecated methods dropped
• ESM/CJS: module system changes

Step 3: Create Upgrade Branch and Install

set -euo pipefail
git checkout -b upgrade/linear-sdk-$(npm view @linear/sdk version)
npm install @linear/sdk@latest

# Immediately check for type errors
npx tsc --noEmit 2>&1 | head -50

Step 4: Fix Type Errors with Compatibility Layer

// src/linear-compat.ts
// Bridge pattern for gradual migration across SDK versions

import { LinearClient } from "@linear/sdk";

/**
 * Normalize issue state access across SDK versions.
 * SDK v2: issue.state was a direct string property
 * SDK v3+: issue.state is a lazy-loaded WorkflowState relation
 */
export async function getIssueStateName(issue: any): Promise<string> {
  if (typeof issue.state === "string") return issue.state;
  const state = await issue.state;
  return state?.name ?? "unknown";
}

export async function getIssueStateType(issue: any): Promise<string> {
  if (typeof issue.stateType === "string") return issue.stateType;
  const state = await issue.state;
  return state?.type ?? "unknown";
}

/**
 * Normalize team access — some versions chan

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 body
• Linear-Delivery — Unique delivery ID for deduplication
• Linear-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: stri