Skip to main content
TL;DRTo integrate Linear webhooks with ngrok:
  1. Launch your local webhook. npm start
  2. Launch ngrok. ngrok http 3000
  3. Configure Linear webhooks with your ngrok URL.
  4. Secure your webhook requests with verification.
This guide covers how to use ngrok to integrate your localhost app with Linear by using Webhooks. Linear webhooks can be used to notify an external application whenever specific events occur in your Linear workspace. By integrating ngrok with Linear, you can:
  • Develop and test Linear webhooks locally - No need to deploy your code and set up HTTPS.
  • Inspect and troubleshoot requests from Linear in real-time using ngrok’s inspection UI and API.
  • Modify and Replay Linear Webhook requests with a single click - No need to reproduce events manually in your Linear workspace.
  • Secure your app with Linear validation provided by ngrok - Invalid requests are blocked by ngrok before reaching your app.

​
What you’ll need

​
1. Start your app

For this tutorial, we’ll use the sample NodeJS app available on GitHub. To install it, run the following commands in a terminal: 
git clone https://github.com/ngrok/ngrok-webhook-nodejs-sample.git
cd ngrok-webhook-nodejs-sample
npm install
Launch the app with the following command: 
npm start
The app runs by default on port 3000. You can validate that the app is up and running by visiting http://localhost:3000. The application logs request headers and body in the terminal and responds with a message in the browser.

​
2. Launch ngrok

If you haven’t done all the preliminary steps for this tutorial, you should do them now.
Once your app is running locally, you’re ready to put it online securely using ngrok.
  1. Start ngrok by running the following command: 
    ngrok http 3000
  2. ngrok will display a URL where your localhost application is exposed to the internet (copy this URL for use with Linear). ngrok agent running

​
3. Integrate Linear

Linear can trigger webhook calls to external applications whenever events happen in your Linear workspace. To register for such events:
  1. Sign in to Linear with an account that has administrative privileges.
  2. Select your profile icon, then select Settings
  3. Navigate to Administration > API.
  4. In the Webhooks section, select Create Webhook. URL
  5. In the Name field, provide something descriptive like “ngrok Integration Webhook”.
  6. In the URL field, enter the URL provided by the ngrok agent to put your app online at that address. For example, your URL might be something like https://1234-abcd-5e6f-7g8h-9i0j.ngrok.app.
  7. Be sure to copy and securely store the Signing secret provided by Linear.
  8. Under the Data change events section, choose the appropriate change events that should trigger the webhook.
  9. Select Create to save the webhook.

​
Get more out of Linear with ngrok

ngrok can do more than just put your Linear application online. Check out these other quick wins ngrok offers you.

​
Run Webhooks with Linear and ngrok

After you create a webhook in Linear, Linear will submit a POST request to your application through ngrok whenever the selected events occur. To trigger a webhook event:
  1. In your Linear workspace, navigate to a project and create a new issue, or update an existing issue.
  2. Confirm your localhost app receives the webhook notification and logs both headers and body in the terminal.
Different messages are sent to your application depending on the trigger event you choose.
To review webhook deliveries in Linear:
  1. Navigate back to Settings > Administration > API > Webhooks.
  2. Select the webhook you’ve just created.
  3. Review the webhook details and recent delivery attempts. Recent Events

​
Inspecting requests

ngrok’s Traffic Inspector captures all requests made through your ngrok endpoint to your localhost app. Select any request to view detailed information about both the request and response.
To avoid exposing secrets, accounts only collect traffic metadata by default. You must enable full capture in the Observability section of your account settings to capture complete request and response data.
Use the traffic inspector to:
  • Validate webhook payloads and response data
  • Debug request headers, methods, and status codes
  • Troubleshoot integration issues without adding logging to your app

​
Replaying requests

Test your webhook handling code without triggering new events from your service using the Traffic Inspector’s replay feature:
  1. Send a test webhook from your service to generate traffic in your Traffic Inspector.
  2. Select the request you want to replay in the traffic inspector.
  3. Choose your replay option:
    • Click Replay to send the exact same request again
    • Select Replay with modifications to edit the request before sending
  4. (Optional) Modify the request: Edit any part of the original request, such as changing field values in the request body.
  5. Send the request by clicking Replay.
Your local application will receive the replayed request and log the data to the terminal.

​
Secure webhook requests

The ngrok signature webhook verification feature allows ngrok to assert that requests from your Linear webhook are the only traffic allowed to make calls to your localhost app.
This ngrok feature is limited to 500 validations per month on free ngrok accounts. For unlimited, upgrade to Pro or Enterprise.
This is a quick step to add extra protection to your application.
  1. In your Linear webhook settings, locate the Secret field. Linear will generate a secret automatically when you create the webhook. Copy this secret value.
  2. Create a traffic policy file named linear_policy.yml, replacing {your secret} with your Secret from Linear: 
    on_http_request:
  - actions:
      - type: verify-webhook
        config:
          provider: linear
          secret: "{your secret}"
  3. Restart your ngrok agent by running the command: 
    ngrok http 3000 --traffic-policy-file linear_policy.yml
  4. In your Linear workspace, create or update an issue to trigger the webhook.
  5. Verify that your local application receives the request and logs information to the terminal.