How to Test Linear Webhooks

Linear has become the default issue tracker for modern engineering teams. If you are building an integration to sync tasks with another tool, trigger deployments based on issue status, or alert your team in Slack, you need to rely on Linear webhooks.

Linear's webhook system is robust, but the payloads can be complex to parse. Testing them effectively requires the right workflow.

The structure of a Linear webhook

Linear webhooks differ slightly from other platforms. When an event happens, Linear sends an HTTP POST request to your specified URL. The payload contains three core properties:

• Action: The type of action that occurred, such as "create", "update", or "remove".
• Type: The entity that was affected, such as "Issue", "Comment", or "Project".
• Data: The actual JSON object representing the entity.

If you are listening for an issue update, you will receive an "update" action for an "Issue" type. The "data" object will contain the new state of the issue, and an additional "updatedFrom" object will show you what the previous values were. This structure makes state tracking powerful but requires careful parsing.

Creating a test environment

If you try to write your integration by just reading the API documentation, you will likely encounter unexpected data structures. You need to capture a real webhook first.

Create an endpoint in Payloader. In Linear, navigate to your workspace settings, select "API", and then "Webhooks". Create a new webhook, paste your Payloader URL, and select the resource types you want to monitor, such as "Issues".

Now, create a test issue in Linear.

Decoding the payload

Instantly, the webhook will arrive in Payloader. Linear payloads can contain dozens of nested IDs representing teams, assignees, and project states. Reading through this raw JSON takes time.

Payloader automatically identifies the Linear webhook. It translates the raw action and type data into a readable summary. For example, it will immediately show "New issue PAY-128: Add webhook retry logic" and break down the priority and assignee. You instantly know the structure of the data you are working with.

Testing locally

To write the logic that handles these issues, you need the webhooks delivered to your local machine.

Use Payloader's webhook forwarding to proxy incoming requests. Point the forwarding destination to your local development server. When you update the test issue in Linear, the webhook travels to Payloader, which instantly passes it down to your localhost environment.

If your code fails to parse the "updatedFrom" object correctly, you do not need to go back to Linear and manipulate the issue again. Simply click "Replay" on the specific webhook in Payloader to run the request through your local code a second time.

Webhook security

Linear secures its webhooks using an HMAC-SHA256 signature, similar to Stripe and GitHub. In your webhook settings in Linear, you will see a secret key.

Every incoming request will include a "linear-signature" header. Your server must use your secret key to hash the raw request body and compare it to this signature. This step is critical before deploying your integration to production to ensure malicious parties cannot inject fake tasks into your system.