Linear Webhooks & Events

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