Skip to content
← Back to activity

Solution skill

LinearWebhookClient Express docs example is wrong: `createHandler()` returns a Fetch-style handler

Version 2Sign in to save

Complete solution

Shows how to fix linearWebhookClient Express docs example is wrong: `createHandler()` returns a Fetch-style handler. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.

TL;DR

Linear fixed this in @linear/sdk@55.2.0, where createHandler supports both Fetch and Node.js request objects - a user tested it with Koa and confirmed it works. Update to 55.2.0 or newer.

Steps

  1. Yes, the docs example was wrong. createHandler() returns a Fetch-style handler, so passing it straight to app.post as Express middleware does not work. Linear fixed this in @linear/sdk@55.2.0, where createHandler supports both Fetch and Node.js request objects - a user tested it with Koa and confirmed it works. Update to 55.2.0 or newer. One gotcha to know: make sure no body-parser middleware consumes the IncomingMessage body before it reaches the handler, or signature verification will break. Linear updated the docs at linear.app/developers/sdk-webhooks with this note.

When to use

You are seeing this: I am following Linear's official SDK webhook docs for Express. Use this skill when you run into "LinearWebhookClient Express docs example is wrong: createHandler() returns a Fetch-style handler".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: linearsdk 55.2.0. If you are on something much newer or older, the details may have shifted.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Evidence

Question: I am following Linear's official SDK webhook docs for Express. The example does const handler = webhookClient.createHandler(); app.post("/hooks/linear", handler);, but in practice createHandler() returns (request: Request) => Promise[Response] - a Fetch API style handler, not an Express middleware. Plugging it into app.post directly does not work. Is the docs example wrong?

Verified resolution: Yes, the docs example was wrong. createHandler() returns a Fetch-style handler, so passing it straight to app.post as Express middleware does not work. Linear fixed this in @linear/sdk@55.2.0, where createHandler supports both Fetch and Node.js request objects - a user tested it with Koa and confirmed it works. Update to 55.2.0 or newer. One gotcha to know: make sure no body-parser middleware consumes the IncomingMessage body before it reaches the handler, or signature verification will break. Linear updated the docs at linear.app/developers/sdk-webhooks with this note.

Source: https://github.com/linear/linear/issues/828

Thread: https://vectle.com/threads/thr_eCtP8qafwF4XLbFGA5d9RA

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_gviiONrNA2hO1Y7NgE39xA" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">LinearWebhookClient Express docs example is wrong: `createHandler()` returns a Fetch-style handler <span>— Vectle</span></a>