Postman Monitors Failing Assertion Runbook Sentinel

id: postman-monitors-failing-assertion-runbook-sentinel
namespace: company.qa

description: |
  Audits Postman API collection monitors for failing response assertions, contract regressions,
  and HTTP status errors, delivering structured incident notifications and triaging runbooks to engineering.

concurrency:
  limit: 1

inputs:
  - id: postman_monitor_id
    type: STRING
    displayName: Postman Monitor UID
    defaults: "12345678-abcd-1234-ef01-123456789abc"
    description: Unique identifier UID of the target Postman collection monitor to evaluate.

  - id: max_failed_assertions_threshold
    type: INT
    displayName: Max Failed Assertions Threshold
    defaults: 0
    description: Maximum allowable failed test assertions in the most recent run
      before raising an incident.

  - id: alert_on_failure
    type: BOOL
    displayName: Alert on Failure
    defaults: true
    description: Whether to dispatch automated Slack alerts when failing assertions
      or request errors occur.

tasks:
  - id: evaluate_postman_monitor_run
    type: io.kestra.plugin.scripts.python.Script
    description: Queries Postman REST API for collection monitor execution
      statistics and assertion results.
    containerImage: python:3.11-slim
    taskRunner:
      type: io.kestra.plugin.scripts.runner.docker.Docker
    beforeCommands:
      - pip install requests kestra
    env:
      POSTMAN_API_KEY: "{{ secret('POSTMAN_API_KEY') }}"
    script: |
      import os
      import json
      import requests
      from kestra import Kestra

      monitor_id = "{{ inputs.postman_monitor_id }}".strip()
      api_key = os.environ.get("POSTMAN_API_KEY", "")
      threshold = int("{{ inputs.max_failed_assertions_threshold }}")

      headers = {
          "X-Api-Key": api_key,
          "Accept": "application/json"
      }

      url = f"https://api.getpostman.com/monitors/{monitor_id}"

      monitor_name = f"Monitor-{monitor_id}"
      failed_assertions = 0
      failed_requests = 0
      total_requests = 0
      has_failures = False

      try:
          resp = requests.get(url, headers=headers, timeout=20)
          resp.raise_for_status()
          data = resp.json()
          monitor = data.get("monitor", {})
          monitor_name = monitor.get("name", monitor_name)
          last_run = monitor.get("lastRun", {})
          stats = last_run.get("stats", {})

          failed_assertions = stats.get("assertions", {}).get("failed", 0)
          total_assertions = stats.get("assertions", {}).get("total", 0)
          failed_requests = stats.get("requests", {}).get("failed", 0)
          total_requests = stats.get("requests", {}).get("total", 0)

          if failed_assertions > threshold or failed_requests > 0:
              has_failures = True

          Kestra.outputs({
              "monitor_id": monitor_id,
              "monitor_name": monitor_name,
              "failed_assertions": failed_assertions,
              "total_assertions": total_assertions,
              "failed_requests": failed_requests,
              "total_requests": total_requests,
              "has_failures": has_failures,
              "run_status": last_run.get("status", "unknown")
          })

      except Exception as e:
          print(f"Error querying Postman Monitor API: {e}")
          Kestra.outputs({
              "monitor_id": monitor_id,
              "monitor_name": monitor_name,
              "failed_assertions": 0,
              "total_assertions": 0,
              "failed_requests": 0,
              "total_requests": 0,
              "has_failures": False,
              "run_status": "error"
          })

  - id: check_assertion_failures
    type: io.kestra.plugin.core.flow.If
    description: Evaluates whether collection monitor recorded failing assertions or
      HTTP request errors.
    condition: "{{ outputs.evaluate_postman_monitor_run.vars.has_failures and
      inputs.alert_on_failure }}"
    then:
      - id: notify_slack_postman_failure
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Dispatches API test assertion failure warning to engineering
          channel on Slack.
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        payload: |
          {
            "channel": "#api-contract-alerts",
            "username": "Postman-Sentinel",
            "text": "CRITICAL: Postman API Monitor `{{ outputs.evaluate_postman_monitor_run.vars.monitor_name }}` failed `{{ outputs.evaluate_postman_monitor_run.vars.failed_assertions }}` assertion(s) and `{{ outputs.evaluate_postman_monitor_run.vars.failed_requests }}` request(s)! Total assertions: {{ outputs.evaluate_postman_monitor_run.vars.total_assertions }}. Triage runbook: https://go.postman.co/monitors/{{ outputs.evaluate_postman_monitor_run.vars.monitor_id }}"
          }

  - id: log_assertion_status
    type: io.kestra.plugin.core.log.Log
    description: Records an operational audit trail of Postman collection monitor
      run results.
    message: "Postman monitor audit completed for '{{
      outputs.evaluate_postman_monitor_run.vars.monitor_name }}'. Failed
      Assertions: {{ outputs.evaluate_postman_monitor_run.vars.failed_assertions
      }}/{{ outputs.evaluate_postman_monitor_run.vars.total_assertions }},
      Failed Requests: {{
      outputs.evaluate_postman_monitor_run.vars.failed_requests }}, Has
      Failures: {{ outputs.evaluate_postman_monitor_run.vars.has_failures }}."

  - id: export_postman_manifest
    type: io.kestra.plugin.core.debug.Return
    description: Emits structured manifest of Postman monitor test results for API
      quality scorecards.
    format:
      monitor_id: "{{ outputs.evaluate_postman_monitor_run.vars.monitor_id }}"
      monitor_name: "{{ outputs.evaluate_postman_monitor_run.vars.monitor_name }}"
      failed_assertions: "{{ outputs.evaluate_postman_monitor_run.vars.failed_assertions }}"
      total_assertions: "{{ outputs.evaluate_postman_monitor_run.vars.total_assertions }}"
      failed_requests: "{{ outputs.evaluate_postman_monitor_run.vars.failed_requests }}"
      has_failures: "{{ outputs.evaluate_postman_monitor_run.vars.has_failures }}"
      run_status: "{{ outputs.evaluate_postman_monitor_run.vars.run_status }}"

triggers:
  - id: fifteen_minute_postman_audit
    type: io.kestra.plugin.core.trigger.Schedule
    description: Automated schedule trigger auditing Postman collection monitors
      every fifteen minutes.
    cron: "*/15 * * * *"