Trigger collection runs using webhooks

A webhook provides a way to automatically send data from one application to another. Using the Postman API’s POST /webhooks endpoint, you can create a webhook for a collection. This creates a monitor that runs the collection when the webhook is triggered at a specific time or when an event occurs.

You can also send a custom payload to the webhook, and Postman can access the data when the collection runs. This means you can run a collection without an environment, and instead rely on the data sent to the webhook.

Create a webhook

With a collection webhook, data is sent to the webhook URL using a POST request when certain events are triggered. You must configure the application that sends the data and the trigger events. Webhooks for a collection must be created using the Postman API. Learn how to use the Postman API to create a webhook.

To access the data sent to the webhook, use the pm.globals.get method with the previousRequest global variable. Using scripts, you can parse that data and use it during the collection run in any way possible.

Access the request body in scripts

When you trigger the webhook, the previousRequest global variable is temporarily created, and its value is the request body of the webhook as a JSON string. Use the pm.globals.get('previousRequest') method to get the request body of the webhook, then parse it using JSON.parse(). The data sent to the webhook is available in the data parameter inside the parsed object, as shown in the following example code:

1
var previousRequest = JSON.parse(pm.globals.get('previousRequest'));
2
3
var webhookRequestData = previousRequest.data;
4
5
// webhookRequestData contains the data sent to your webhook.
6
console.log(JSON.stringify(webhookRequestData));

When you create a webhook using the Postman API, a monitor is created for the webhook. You must trigger the webhook in a separate request to run the example code using the monitor. Then you can view the monitor run details that were logged to Console. To learn more about monitor results, see View monitor results.

Send output to another API

Use the data that’s sent to the collection webhook to define logic and trigger another API. For example, you might set up a webhook for your GitHub repository. Based on the updates happening in your repository, you can use the webhook to run custom build pipelines or perform CI tests.