Webhooks

The SDK provides a helper class to help you start listening to Linear webhook events quickly.

Use LinearWebhookClient to create a typed, signature-verified event listener that can be mounted on Bun, Fastify, Express, or other server frameworks, so you can start working with webhook events with minimal boilerplate.

import { LinearWebhookClient } from "@linear/sdk/webhooks";
 
// Example with Express
const app = express();
const webhookClient = new LinearWebhookClient("WEBHOOK_SECRET");
 
// Create an HTTP handler
const handler = webhookClient.createHandler();
 
// Handle the webhook event
handler.on("Issue", (payload) => {
  console.log(payload.data.title);
  ...
});
 
// Mount handler to your server
app.post("/hooks/linear", handler);

It also provides a helper to verify webhook signatures, in case you'd like to handle the webhook events manually:

import { 
  LinearWebhookClient,
  LINEAR_WEBHOOK_SIGNATURE_HEADER, 
  LINEAR_WEBHOOK_TS_FIELD
} from '@linear/sdk/webhooks';
 
const webhookClient = new LinearWebhookClient("WEBHOOK_SECRET");
 
// Example with Express
app.use(
  "/hooks/linear",
  bodyParser.json({
    verify: (req, res, buf) => {
      webhookClient.verify(
        buf,
        req.headers[LINEAR_WEBHOOK_SIGNATURE_HEADER] as string,
        JSON.parse(buf.toString())[LINEAR_WEBHOOK_TS_FIELD],
      );
    },
  }),
  (req, res, next) => {
    // Handle the webhook event
    next();
  },
);

Advanced usage

Migrating from 1.x to 2.x