# How to run a monitor with the Postman API

[Postman Monitors](https://learning.postman.com/docs/monitoring-your-api/intro-monitors/) provide continuous visibility into the health and performance of your APIs. Collection-based monitors let you run API test scripts, chain together multiple requests, and validate critical API flows. While you probably know that you can[ schedule monitors](https://learning.postman.com/docs/collections/running-collections/scheduling-collection-runs-monitors/) to run at specific intervals or manually run monitors, did you know that you can also run monitors using the[ Postman API](https://www.postman.com/postman/workspace/postman-public-workspace/documentation/12959542-c8142d51-e97c-46b6-bd77-52bb66712c9a?entity=&branch=&version=)? With the Postman API's [/monitors endpoints](https://www.postman.com/postman/workspace/postman-public-workspace/folder/12959542-e8688124-26f9-4dbe-9226-0c453fedf8a9), you can integrate monitor runs in your workflows, such as CI/CD tooling, your [API monitoring](https://www.postman.com/api-platform/api-monitoring/) dashboards, or any other app that you use. In this blog post, we’ll show you how to use the Postman API to run a monitor. There are two ways you can run a monitor with the Postman API: using the `monitors` or `webhook` endpoints. ### Monitors endpoints

 You can use Postman API’s[ Monitors resource](https://www.postman.com/postman/workspace/postman-public-workspace/documentation/12959542-c8142d51-e97c-46b6-bd77-52bb66712c9a?entity=folder-e8688124-26f9-4dbe-9226-0c453fedf8a9&branch=&version=) to create, read, update, and delete your monitor resources. You can use the `Run a monitors` endpoint to run the monitor synchronously and get information about the run. This is a basic JavaScript example that shows how you can use the `Run a monitors` endpoint: ```
var myHeaders = new Headers();
myHeaders.append("X-API-Key", "");

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://api.getpostman.com/monitors/{{monitorId}}/run", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
```

### Webhooks endpoint

 The[ Create a webhook](https://www.postman.com/postman/workspace/postman-public-workspace/request/12959542-7552368b-7fc3-4f9b-a3e2-e229c3f6d299) endpoint allows you to[ trigger the run of a collection](https://learning.postman.com/docs/collections/running-collections/collection-webhooks/) with a webhook. This is how it works: 1. Create a webhook with the `Create a webhook` endpoint. The request body must contain the webhook’s name (`webhookName`) and the UID of the Postman Collection (`collectionUid`) you want to run. For example: ```
    {
        "webhook":{
            "name": "Blogpost webhook",
            "collection": "12345678-42717b5c-0b9c-11ee-be56-0242ac120002"
        }
    }
    
    ```
2. The request you send creates a monitor linked to the collection. The response returns the monitor’s name and its ID. The response also returns the `webhookUrl` property: ![A successful response from the Create a webhook endpoint in Postman.](https://blog.postman.com/wp-content/uploads/2023/07/create-webhook-response-300x218.jpg)
3. **Important note: The** `webhookUrl` **value contains sensitive information, so** **treat it like you would a password.** Calls to the webhook’s URL *do not* require authentication.
4. A POST to the `webhookUrl` runs the monitor and the collection.
 
 The valid JSON body you post passes to the collection. You can get it with the following code in a pre-request script: ```
let previousRequest = JSON.parse(globals.previousRequest),
    webhookRequestData = previousRequest.data;

// webhookRequestData contains the data sent to your webhook.
console.log(JSON.stringify(webhookRequestData));

```

 This pre-request script allows you to receive dynamic data and not depend on an environment. You can also check the webhook’s monitor runs with Postman Monitors: ![A view of a webhook’s monitor runs in Postman.](https://blog.postman.com/wp-content/uploads/2023/07/webhook-status-report-300x195.png)## Differences between monitors and webhooks endpoints

 First, what’s the difference between using the `monitors` endpoint and the `webhooks` endpoint? - With `webhooks`, you don’t need an environment when you run a monitor. The collection gets information from the posted body and operates with that data. You can't do this with a regular monitor.
- No authorization is required when calling the webhook. If you run a monitor with the Postman API’s `monitors` endpoints, you need authentication. Rate limits also apply to `webhooks` and `monitors` calls.
- If you need information about a monitor’s run, then you’ll need to use the `monitors` endpoints. This is because the webhook call doesn't return that information—it only triggers the run.
- You can’t create, read, update, or delete a webhook. However, you can do so with monitors using the Postman API.
 
 So when should you use `webhooks` instead of `monitors` endpoints? If you want to run a complex collection that requires dynamic parameters, then using `webhooks` is the solution. You can set collection variables based on the `previousRequest` posted data and have different behavior based on that, which makes webhooks very powerful. ## Using a GitHub action to run a monitor with the Postman API

 We’ve integrated a request to the[ Run a monitor](https://www.postman.com/postman/workspace/postman-public-workspace/request/12959542-688c4c2a-58b6-4f26-b06b-1f45508ee1d4?ctx=documentation) endpoint into a GitHub action. You can use this action in your repository to run a monitor when a specific GitHub event occurs and check the run’s results. Before getting started, you’ll need the following: - A[ GitHub](https://github.com/) repository
- A valid[ Postman API key](https://learning.postman.com/docs/developer/postman-api/authentication/#generate-a-postman-api-key)
- The monitor’s ID. To get it, find your monitor, then click on the information icon and copy the **ID** as show below: ![The Postman Monitor’s information tab.](https://blog.postman.com/wp-content/uploads/2023/07/monitor-info-300x203.jpg)
 
### Use the GitHub action

 The GitHub action code is available in the[ **execute-postman-monitor**](https://github.com/postmanlabs/execute-postman-monitor) repository. The following is an example of the action’s trigger on a pull request called `Execute Postman Monitor`: ```
name: Execute Postman Monitor
on:
  pull_request:
jobs:
  execute-postman-monitor:
    runs-on: ubuntu-latest
    steps:
      - name: Execute Postman Monitor
        id: executeMonitor
        uses: postmanlabs/execute-postman-monitor@v1
        with:
          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
          monitor-id: ${{ vars.MONITOR_ID }}
```

 In this example, the action runs when a pull request is created. It also reads the parameters it needs from the repository’s secrets and variables. Now that we have what we need, let’s configure and run the GitHub action. ### 1. Configure your GitHub repository

 Make the following configuration changes to your GitHub repository: #### **Create the workflow**

 You’ll need to first create the workflow. Give this file a meaningful name so it makes it easy to see what it does. For this tutorial, we’ll use the *execute-postman.monitor.yml* file name. In your GitHub repository, create the *execute-postman.monitor.yml* file in the *.github/workflows* folder. If the *.github/workflows* folder does not exist, you’ll need to create it, then add the file to this folder. You can also create the workflow in the GitHub **Actions** tab. Select **New workflow**, then **Configure** in **Simple workflow**. Update the file name and the GitHub action code. #### **Set up environment variables**

 In the GitHub repository’s **Settings** **> Secrets and variables > Actions** tab: - In **Variables**, create the `MONITOR_ID` repository variable and add the Postman Monitor’s ID.
- In **Secrets**, create a `POSTMAN_API_KEY` repository secret. This contains a valid[ Postman API key](https://go.postman.co/settings/me/api-keys).
 
 When you’re finished, commit these changes to your repository. ### 2. Run the GitHub action

 After you configure the action, the action automatically runs when a pull request is created on the repository: ![The GitHub action’s successful run.](https://blog.postman.com/wp-content/uploads/2023/07/github-action-success-300x121.png) You can check the monitor’s results (`success` or `failed`) in the logs: ![The GitHub action’s logs.](https://blog.postman.com/wp-content/uploads/2023/07/github-action-log-300x88.jpg) Additionally, this action sets a `status` output variable when it completes that other actions in the workflow can use. This action is not intended to fail unless the monitor can’t run. Even if the monitor returns a `failed` result, this GitHub action won't fail. ### Next steps

 This is a basic action that uses a Postman API call on an existing Postman Monitor. However, you can take this a step further and dynamically create a monitor, run it, then delete the monitor—all with Postman’s[ Monitor APIs](https://www.postman.com/postman/workspace/postman-public-workspace/documentation/12959542-c8142d51-e97c-46b6-bd77-52bb66712c9a?entity=folder-e8688124-26f9-4dbe-9226-0c453fedf8a9&branch=&version=). ## Summary

 This is just one of the ways you can use the power of the Postman API to help you automate your software development process. Explore our[ Postman API documentation](https://www.postman.com/postman/workspace/postman-public-workspace/documentation/12959542-c8142d51-e97c-46b6-bd77-52bb66712c9a?entity=&branch=&version=) and let us know in a comment below if you discover any other great ways to automate your workflows with the Postman API!