How to run a monitor with the Postman API

đź“š Technical Articles
, ,
1

Postman 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.

With the Postman API’s /monitors endpoints you can integrate monitor runs in your workflows, such as CI/CD tooling, your monitoring dashboards, or any other app that you use. In this 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 to create, read, update, and delete your monitor resources. You can use the Run a monitor endpoint to run a monitor synchronously and get information about the run with the async query string parameter.

This basic JavaScript example shows how you can use this 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));

The webhooks endpoint

The Create a webhook endpoint allows you to trigger the run of a collection with a webhook:

  1. Create a webhook with the POST /webhooks 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"
    }
}
  1. The request you send creates a monitor linked to the collection. The response contains the monitor’s name and ID in the response, as well as the webhook’s URL:
  2. A POST to the webhookUrl runs the monitor and the collection.

The valid JSON body you post passes to the collection. You can use a pre-request script to receive dynamic data and not rely on an environment 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));

You can also view the webhook’s monitor runs results with Postman Monitors:

Monitors vs. webhooks endpoints

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 webhooks. If you run a monitor with the Postman API’s /monitors endpoints, you need authentication (rate limits do apply to both /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, but you can do so with monitors using the Postman API.

So when should you use webhooks?

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 behaviors based on that. This makes webhooks very powerful.

Use GitHub actions to run monitors with the Postman API

We’ve integrated the request to the Run a monitor endpoint into a GitHub action available in the execute-postman-monitor repository. You can use it in your repository to run a monitor when a specific GitHub event occurs and check the run’s results.

To get started, you’ll need the following:

1. Configure your repository

Make the following configuration changes to your GitHub repository:

Create the workflow

First, create the workflow. Give the file a meaningful name so it’s easy to see what it does. For this tutorial, we’ll use the execute-postman.monitor.yml file name.

Next, create the file in the repository’s .github/workflows folder. If the folder doesn’t 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, do the following:

  • In Variables, create the MONITOR_ID repository variable and add the monitor’s ID.
  • In Secrets, create a POSTMAN_API_KEY repository secret. This contains a valid Postman API key.

When you’re finished, commit these changes to your repository.

2. Run the action

After you configure the action, it automatically runs when a pull request is created:

You can check the monitor’s results (success or failed) in the logs. 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 Monitors APIs.

Explore our Postman API documentation and let us know if you discover any other great ways to automate your workflows with the Postman API!

5 Likes