openapi: 3.1.0
info:
  title: Postman Webhooks API
  description: |
    The Postman Webhooks API enables you to create webhooks that trigger
    collection runs with custom payloads. Webhooks provide a way to integrate
    Postman with external systems and automate workflows based on incoming
    events. When a webhook URL receives a POST request, it triggers a
    collection run with the incoming payload available as variables.

    ## Authentication
    All requests require an API key passed in the `x-api-key` header.

    ## Rate Limits
    Standard Postman API rate limits apply.
  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/
servers:
  - url: https://api.getpostman.com
    description: Postman Production API Server
tags:
  - name: Webhooks
    description: Operations for creating and managing Postman webhooks.
security:
  - apiKeyAuth: []
paths:
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Postman Create a webhook
      operationId: createWebhook
      description: >-
        Creates a webhook that triggers a collection run when its generated
        URL receives a POST request. The incoming request body is available
        as variables during the collection run.
      parameters:
        - name: workspace
          in: query
          description: The workspace ID to create the webhook in.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook
              properties:
                webhook:
                  type: object
                  required:
                    - name
                    - collection
                  properties:
                    name:
                      type: string
                      description: The webhook name
                    collection:
                      type: string
                      description: The collection UID to run when the webhook is triggered
      responses:
        '200':
          description: Successfully created webhook
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook:
                    $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header
      description: Postman API key for authentication.
  schemas:
    Webhook:
      type: object
      description: A Postman webhook that triggers collection runs on HTTP POST requests.
      properties:
        id:
          type: string
          description: The webhook's unique ID
        name:
          type: string
          description: The webhook name
        collection:
          type: string
          description: The collection UID being triggered
        webhookUrl:
          type: string
          format: uri
          description: The URL that triggers the webhook when it receives a POST request
        uid:
          type: string
          description: The webhook's UID
        createdAt:
          type: string
          format: date-time
  responses:
    BadRequestError:
      description: Bad request - invalid input
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
    UnauthorizedError:
      description: Authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
    RateLimitError:
      description: Too many requests - rate limit exceeded
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              message:
                type: string
    InternalServerError:
      description: An unexpected error occurred on the server
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string