postman-webhooks-asyncapi.yml

asyncapi: 2.6.0
info:
  title: Postman Webhooks
  description: >-
    Postman Webhooks enable you to receive incoming HTTP POST requests that
    trigger collection runs. When an external system sends a POST request to
    a Postman webhook URL, the webhook triggers a collection run and makes the
    incoming payload available as variables during the run. This provides a way
    to integrate Postman with CI/CD pipelines, monitoring systems, and other
    external services that need to trigger automated API testing workflows.

    Postman also supports custom webhooks for monitor notifications, which
    deliver alerts about monitor run failures and errors to your configured
    endpoints.
  version: '1.0.0'
  contact:
    name: Postman Developer Support
    url: https://learning.postman.com/docs/developer/postman-api/intro-api/
    email: help@postman.com
  license:
    name: Postman Terms of Service
    url: https://www.postman.com/legal/terms/
  externalDocs:
    description: Postman Webhooks Documentation
    url: https://learning.postman.com/docs/developer/postman-api/intro-api/
servers:
  webhook-receiver:
    url: '{webhookUrl}'
    protocol: https
    description: >-
      Your webhook receiver endpoint. External systems send POST requests to
      the Postman-generated webhook URL to trigger collection runs. The webhook
      URL is generated when you create a webhook via the Postman API.
    variables:
      webhookUrl:
        description: >-
          The webhook URL generated by Postman when the webhook is created.
          This URL is unique to each webhook and includes authentication
          built into the URL path.
  monitor-notification-receiver:
    url: '{notificationUrl}'
    protocol: https
    description: >-
      Your notification endpoint that receives monitor run results. Configure
      this URL in your Postman monitor's notification settings or through
      integrations.
    variables:
      notificationUrl:
        description: >-
          The URL configured to receive monitor notification webhooks.
channels:
  /webhook/trigger:
    description: >-
      Channel for incoming webhook triggers that initiate collection runs.
      When an external system sends a POST request to the webhook URL, Postman
      triggers the associated collection run and passes the request payload
      as variables available during the run.
    publish:
      operationId: triggerCollectionRun
      summary: Trigger a collection run via webhook
      description: >-
        External systems send POST requests with JSON payloads to this
        channel. The payload data becomes available as variables in the
        collection being run, accessible via pm.variables.get() in
        pre-request and test scripts.
      bindings:
        http:
          type: request
          method: POST
          headers:
            type: object
            properties:
              Content-Type:
                type: string
                enum: [application/json]
      message:
        $ref: '#/components/messages/WebhookTriggerPayload'
  /webhook/monitor-notification:
    description: >-
      Channel for outgoing monitor run notifications. When a monitor run
      completes with failures or errors, Postman sends a notification to
      configured webhook endpoints with details about the run results.
    subscribe:
      operationId: receiveMonitorNotification
      summary: Receive a monitor run notification
      description: >-
        Postman sends monitor run result notifications as HTTP POST requests
        with JSON payloads to configured webhook endpoints. Notifications are
        sent when a monitor run completes with test failures or errors.
      bindings:
        http:
          type: request
          method: POST
          headers:
            type: object
            properties:
              Content-Type:
                type: string
                enum: [application/json]
              User-Agent:
                type: string
                description: Postman user agent string
      message:
        $ref: '#/components/messages/MonitorNotification'
  /webhook/integration-notification:
    description: >-
      Channel for integration webhook notifications. Postman can send
      notifications to external services (Slack, Microsoft Teams, PagerDuty,
      etc.) when specific events occur, such as monitor failures, collection
      updates, or team activity changes.
    subscribe:
      operationId: receiveIntegrationNotification
      summary: Receive an integration notification
      description: >-
        Postman sends event notifications to configured integration endpoints.
        These notifications are triggered by various Postman events and
        delivered as HTTP POST requests.
      bindings:
        http:
          type: request
          method: POST
          headers:
            type: object
            properties:
              Content-Type:
                type: string
                enum: [application/json]
      message:
        $ref: '#/components/messages/IntegrationNotification'
components:
  messages:
    WebhookTriggerPayload:
      name: WebhookTriggerPayload
      title: Webhook Trigger Payload
      summary: >-
        The payload sent to a Postman webhook URL to trigger a collection run.
        The payload contents are user-defined and become available as variables
        during the collection run.
      contentType: application/json
      payload:
        type: object
        description: >-
          User-defined payload. All top-level keys become available as
          variables in the collection run via pm.variables.get(key).
        additionalProperties: true
        example:
          environment: production
          buildNumber: "1234"
          triggeredBy: ci-pipeline
          testSuite: regression
    MonitorNotification:
      name: MonitorNotification
      title: Monitor Run Notification
      summary: >-
        Notification sent when a Postman monitor run completes. Contains
        run results including test pass/fail counts, response times, and
        error details.
      contentType: application/json
      payload:
        type: object
        properties:
          monitorId:
            type: string
            description: The monitor's unique ID
          monitorName:
            type: string
            description: The monitor's display name
          collectionUid:
            type: string
            description: The UID of the collection that was run
          environmentUid:
            type: string
            description: The UID of the environment used during the run
          status:
            type: string
            enum: [success, failure, error, abort]
            description: The overall run status
          startedAt:
            type: string
            format: date-time
            description: When the run started
          finishedAt:
            type: string
            format: date-time
            description: When the run completed
          stats:
            type: object
            properties:
              requests:
                type: object
                properties:
                  total:
                    type: integer
                  failed:
                    type: integer
              assertions:
                type: object
                properties:
                  total:
                    type: integer
                  failed:
                    type: integer
          failures:
            type: array
            description: Details of failed test assertions
            items:
              type: object
              properties:
                name:
                  type: string
                  description: The test assertion name
                error:
                  type: string
                  description: The error message
                request:
                  type: object
                  properties:
                    name:
                      type: string
                    method:
                      type: string
                    url:
                      type: string
                response:
                  type: object
                  properties:
                    statusCode:
                      type: integer
                    responseTime:
                      type: integer
          region:
            type: string
            description: The region the monitor ran from
    IntegrationNotification:
      name: IntegrationNotification
      title: Integration Notification
      summary: >-
        Notification sent to external integrations when specific Postman
        events occur, such as monitor failures, collection updates, or
        team changes.
      contentType: application/json
      payload:
        type: object
        properties:
          event:
            type: string
            description: The event type that triggered the notification
            enum:
              - monitor.run.success
              - monitor.run.failure
              - monitor.run.error
              - collection.updated
              - environment.updated
              - team.member_added
              - team.member_removed
          timestamp:
            type: string
            format: date-time
          data:
            type: object
            description: Event-specific data. Structure varies by event type.
            additionalProperties: true