Skip to main content
TL;DRTo integrate Jira webhooks with ngrok:
  1. Launch your local webhook. npm start
  2. Launch ngrok. ngrok http 3000
  3. Configure Jira 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 Jira by using Webhooks. Jira webhooks can be used to notify an external application whenever specific events occur in your Jira instance. By integrating ngrok with Jira, you can:
  • Develop and test Jira webhooks locally - No need to deploy your code and set up HTTPS.
  • Inspect and troubleshoot requests from Jira in real-time using ngrok’s inspection UI and API.
  • Modify and Replay Jira Webhook requests with a single click - No need to reproduce events manually in your Jira instance.
  • Secure your app with Jira 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 your 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 Jira). ngrok agent running

​
3. Integrate Jira

Jira can trigger webhook calls to external applications whenever events happen in your instance. To register for such events:
  1. Sign in to Jira with an account that has the Jira Administrators global permission.
  2. Navigate to the Settings icon (⚙️) and select System.
  3. Under the Advanced section, select WebHooks, then select Create a WebHook.
  4. In the Name field, provide something descriptive like “ngrok Integration Webhook”.
  5. 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. URL
  6. Under the Events section, select the specific events that should trigger the webhook.
  7. (Optional) To limit the scope of the webhook, you can specify a JQL (Jira Query Language) query in the JQL field. For example, to trigger the webhook only for issues in specific projects: 
    project in (ABC, XYZ)
  8. Finally, select Create.

​
Get more out of Jira with ngrok

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

​
Run Webhooks with Jira and ngrok

After you create a webhook in Jira, Jira will submit a POST request to your application through ngrok whenever the selected events occur. To trigger a webhook event:
  1. In your Jira instance, 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.

​
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 Jira 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 Jira webhook settings, locate the Secret field. If a secret is not already set, you can generate one or use a custom secret value. Copy this secret value.
  2. Create a traffic policy file named jira_policy.yml, replacing {your secret} with your Secret from Jira: 
    on_http_request:
  - actions:
      - type: verify-webhook
        config:
          provider: jira
          secret: "{your secret}"
  3. Restart your ngrok agent by running the command: 
    ngrok http 3000 --traffic-policy-file jira_policy.yml
  4. In your Jira instance, create or update an issue to trigger the webhook.
  5. Verify that your local application receives the request and logs information to the terminal.