Process Street Workflow Incoming Webhooks API

openapi: 3.2.0
info:
  title: Process Street Public Workflow Incoming Webhooks API
  version: '1.1'
  description: The Process Street API is organized around REST.
servers:
- url: https://public-api.process.st/api/v1.1
tags:
- name: Workflow Incoming Webhooks
  description: 'An incoming webhook triggers workflow runs from external systems.

    Use these endpoints to create, view, update, and delete incoming webhooks for a workflow.'
  externalDocs:
    url: https://www.process.st/help/docs/run-via-webhook/
    description: Process Street help article
paths:
  /workflows/{workflowId}/incoming-webhooks:
    get:
      tags:
      - Workflow Incoming Webhooks
      summary: List incoming webhooks
      description: Returns all non-deleted incoming webhooks for a workflow, including disabled ones.
      operationId: listWorkflowIncomingWebhooks
      parameters:
      - name: workflowId
        in: path
        description: The ID of the Workflow
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiIncomingWebhookListResponse'
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
    post:
      tags:
      - Workflow Incoming Webhooks
      summary: Create an incoming webhook
      description: 'Creates an incoming webhook for a workflow. When the webhook URL receives a JSON payload,

        it creates a workflow run and populates it using the configured mappings.


        **config.properties** maps workflow run properties to JSON paths in the incoming payload:

        - `Name` — run name (string)

        - `DueDate` — due date (ISO 8601 date string)

        - `Shared` — whether the run is shared (boolean)

        - `Assignees` — assignee email addresses (string or array of strings)

        - `Runner` — runner email address (string)


        **config.formFields** maps form field widget IDs to JSON paths for populating form field values

        on the created run. Keys are widget IDs (Muid), values are JSON path expressions (e.g. `$.user.name`).'
      operationId: createWorkflowIncomingWebhook
      parameters:
      - name: workflowId
        in: path
        description: The ID of the Workflow
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflowIncomingWebhookRequest'
            examples:
              Full config:
                summary: Webhook with run properties and form field mappings
                value:
                  name: New Employee Onboarding
                  automationApp: Zapier
                  config:
                    properties:
                      Name: $.employee.name
                      DueDate: $.employee.start_date
                      Assignees: $.employee.manager_email
                    formFields:
                      gcWPxsRjNNTeZqaTsBpLhg: $.employee.department
                      ocsAkBEFkTih7YpuSfJEnw: $.employee.role
              Minimal:
                summary: Webhook with no mappings — creates a blank workflow run
                value:
                  name: Simple trigger
                  automationApp: Custom
                  config: {}
        required: true
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiIncomingWebhookResponse'
        '400':
          description: 'Invalid value for: body'
          content:
            text/plain:
              schema:
                type: string
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
  /workflows/{workflowId}/incoming-webhooks/{webhookId}:
    get:
      tags:
      - Workflow Incoming Webhooks
      summary: Get an incoming webhook
      description: Returns an incoming webhook by its ID for a workflow.
      operationId: getWorkflowIncomingWebhook
      parameters:
      - name: workflowId
        in: path
        description: The ID of the Workflow
        required: true
        schema:
          type: string
      - name: webhookId
        in: path
        description: The ID of the Webhook
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiIncomingWebhookResponse'
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
    put:
      tags:
      - Workflow Incoming Webhooks
      summary: Update an incoming webhook
      description: 'Updates an incoming webhook for a workflow. PUT semantics: all fields must be provided. Returns the updated webhook.


        See the create endpoint for details on `config.properties` and `config.formFields`.'
      operationId: updateWorkflowIncomingWebhook
      parameters:
      - name: workflowId
        in: path
        description: The ID of the Workflow
        required: true
        schema:
          type: string
      - name: webhookId
        in: path
        description: The ID of the Webhook
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkflowIncomingWebhookRequest'
            examples:
              Update with active status:
                summary: Update webhook mappings while keeping it active
                value:
                  name: New Employee Onboarding (v2)
                  automationApp: Zapier
                  status: Active
                  config:
                    properties:
                      Name: $.employee.full_name
                      DueDate: $.employee.start_date
                      Assignees: $.employee.manager_email
                    formFields:
                      gcWPxsRjNNTeZqaTsBpLhg: $.employee.department
                      ocsAkBEFkTih7YpuSfJEnw: $.employee.role
              Disable webhook:
                summary: Disable a webhook to stop processing incoming payloads
                value:
                  name: Paused webhook
                  automationApp: Custom
                  status: Disabled
                  config: {}
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiIncomingWebhookResponse'
        '400':
          description: 'Invalid value for: body'
          content:
            text/plain:
              schema:
                type: string
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
    delete:
      tags:
      - Workflow Incoming Webhooks
      summary: Delete an incoming webhook
      description: Soft-deletes an incoming webhook for a workflow. Subsequent GET requests will return 404.
      operationId: deleteWorkflowIncomingWebhook
      parameters:
      - name: workflowId
        in: path
        description: The ID of the Workflow
        required: true
        schema:
          type: string
      - name: webhookId
        in: path
        description: The ID of the Webhook
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
components:
  schemas:
    CreateWorkflowIncomingWebhookRequest:
      title: CreateWorkflowIncomingWebhookRequest
      type: object
      required:
      - name
      - automationApp
      - config
      properties:
        name:
          description: Display name.
          type: string
        automationApp:
          type: string
        config:
          title: CreateWorkflowIncomingWebhookConfigRequest
          description: Field-specific configuration. Shape depends on `fieldType`.
          type: object
          properties:
            properties:
              description: Mapping from workflow-run property names (e.g. `Name`, `DueDate`, `Assignees`) to JSONPath expressions in the incoming payload.
              type: object
              additionalProperties:
                type: string
            formFields:
              description: Mapping from form-field IDs to JSONPath expressions in the incoming payload.
              type: object
              additionalProperties:
                type: string
    UpdateWorkflowIncomingWebhookRequest:
      title: UpdateWorkflowIncomingWebhookRequest
      type: object
      required:
      - name
      - automationApp
      - status
      - config
      properties:
        name:
          description: Display name.
          type: string
        automationApp:
          type: string
        status:
          description: 'Incoming webhook lifecycle.


            - `Active` — the webhook accepts and processes incoming payloads.

            - `Disabled` — the URL still resolves but payloads are dropped without triggering a run.

            - `Deleted` — the webhook is soft-deleted; only returned by endpoints that explicitly include deleted records.

            '
          type: string
          enum:
          - Active
          - Disabled
          - Deleted
        config:
          title: CreateWorkflowIncomingWebhookConfigRequest
          description: Field-specific configuration. Shape depends on `fieldType`.
          type: object
          properties:
            properties:
              description: Mapping from workflow-run property names (e.g. `Name`, `DueDate`, `Assignees`) to JSONPath expressions in the incoming payload.
              type: object
              additionalProperties:
                type: string
            formFields:
              description: Mapping from form-field IDs to JSONPath expressions in the incoming payload.
              type: object
              additionalProperties:
                type: string
    PublicApiIncomingWebhookListResponse:
      title: PublicApiIncomingWebhookListResponse
      type: object
      properties:
        data:
          description: The list of resources returned by this request.
          type: array
          items:
            title: PublicApiIncomingWebhook
            type: object
            required:
            - id
            - createdDate
            - createdBy
            - updatedDate
            - updatedBy
            - workflowId
            - name
            - automationApp
            - status
            - url
            - config
            properties:
              id:
                title: EntityID
                description: The resource's ID.
                type: string
              createdDate:
                description: When the resource was first created. ISO-8601 UTC.
                type: string
                format: date-time
              createdBy:
                description: User who created the resource.
                examples:
                - id: iAaSNCU5lWLYGAi663hO8Q
                  email: jane.doe@example.com
                  username: Jane Doe
                type: object
                required:
                - id
                - email
                - username
                properties:
                  id:
                    title: EntityID
                    description: The resource's ID.
                    type: string
                  email:
                    description: The user's email address (also their login identifier).
                    type: string
                  username:
                    description: The user's display name (e.g. `Jane Doe`).
                    type: string
              updatedDate:
                description: When the resource was last modified. ISO-8601 UTC.
                type: string
                format: date-time
              updatedBy:
                description: User who last modified the resource.
                examples:
                - id: iAaSNCU5lWLYGAi663hO8Q
                  email: jane.doe@example.com
                  username: Jane Doe
                type: object
                required:
                - id
                - email
                - username
                properties:
                  id:
                    title: EntityID
                    description: The resource's ID.
                    type: string
                  email:
                    description: The user's email address (also their login identifier).
                    type: string
                  username:
                    description: The user's display name (e.g. `Jane Doe`).
                    type: string
              workflowId:
                description: The ID of the Workflow
                examples:
                - ucBWWop27GXEGmStvtRH_Q
                type: string
              name:
                description: Human-readable label for the webhook (e.g. "Salesforce → Onboarding").
                type: string
              automationApp:
                description: Label of the automation app or integration source (e.g. `Zapier`, `Custom`, `Salesforce`).
                type: string
              status:
                description: Whether the incoming webhook is currently accepting payloads. `Active` — incoming requests at the webhook URL create or update a workflow run. `Disabled` — the webhook URL is configured but requests are ignored.
                type: string
                enum:
                - Active
                - Disabled
              url:
                description: Public URL to POST payloads to. Include this in the upstream system's webhook config.
                type: string
              config:
                title: PublicApiIncomingWebhookConfig
                description: Field-specific configuration. Shape depends on `fieldType`.
                type: object
                required:
                - properties
                - formFields
                properties:
                  properties:
                    description: Mapping from workflow-run property names (e.g. `Name`, `DueDate`, `Assignees`) to JSONPath expressions in the incoming payload.
                    type: object
                    additionalProperties:
                      type: string
                  formFields:
                    description: Mapping from form-field IDs to JSONPath expressions in the incoming payload.
                    type: object
                    additionalProperties:
                      type: string
              links:
                description: Navigable HATEOAS links to related resources. Each entry has a `name` (RFC-5988 link relation like `self`, `edit`, `related`), an `href` URL, and a `type` (`Api` for callable endpoints, `App` for browser-facing URLs). Prefer following these `href` values over constructing URLs by hand.
                type: array
                items:
                  title: Link
                  description: A HATEOAS link to a related resource. Use these to navigate between resources without constructing URLs by hand.
                  type: object
                  required:
                  - name
                  - href
                  - type
                  properties:
                    name:
                      description: Standard link relation name (RFC 5988) indicating this link's role. Common values include `self`, `edit`, `related`, `previous`, `next`.
                      type: string
                    href:
                      title: Uri
                      description: URL of the linked resource.
                      examples:
                      - https://api.process.st/api/v1.1/resource/XXX
                      type: string
                    rel:
                      description: Optional. The kind of resource this link points to (e.g. `Workflow`, `Task`, `Comment`).
                      type: string
                      enum:
                      - Approval Task
                      - Approvals
                      - Assignees
                      - Comment
                      - Data Set Records
                      - Data Sets
                      - Form Field Values
                      - Subject Task
                      - Task
                      - Tasks
                      - Users
                      - Webhook
                      - Workflow
                      - Workflow Run
                    type:
                      description: Whether this link targets an API endpoint or a Process Street app URL. `Api` — a callable API endpoint you can fetch directly. `App` — a browser-facing URL in the Process Street UI.
                      type: string
                      enum:
                      - Api
                      - App
        links:
          description: 'Pagination links. When the result has more pages, look for an entry with `name: "next"` — its `href` is the URL to fetch the next page. Absence of `next` means there are no more pages. For single-resource responses this array is typically empty.'
          type: array
          items:
            title: Link
            description: A HATEOAS link to a related resource. Use these to navigate between resources without constructing URLs by hand.
            type: object
            required:
            - name
            - href
            - type
            properties:
              name:
                description: Standard link relation name (RFC 5988) indicating this link's role. Common values include `self`, `edit`, `related`, `previous`, `next`.
                type: string
              href:
                title: Uri
                description: URL of the linked resource.
                examples:
                - https://api.process.st/api/v1.1/resource/XXX
                type: string
              rel:
                description: Optional. The kind of resource this link points to (e.g. `Workflow`, `Task`, `Comment`).
                type: string
                enum:
                - Approval Task
                - Approvals
                - Assignees
                - Comment
                - Data Set Records
                - Data Sets
                - Form Field Values
                - Subject Task
                - Task
                - Tasks
                - Users
                - Webhook
                - Workflow
                - Workflow Run
              type:
                description: Whether this link targets an API endpoint or a Process Street app URL. `Api` — a callable API endpoint you can fetch directly. `App` — a browser-facing URL in the Process Street UI.
                type: string
                enum:
                - Api
                - App
    ErrorInfo:
      title: ErrorInfo
      type: object
      required:
      - error
      properties:
        error:
          description: 'Human-readable error message. Suitable for logs or for surfacing to end users; do not parse it

            programmatically — use `errorCode` for that.'
          type: string
        details:
          description: 'Optional structured context. Shape depends on the error: for `Validation` errors the keys are field

            paths; for `PaymentRequired` the keys describe the limit that was hit.'
          type: object
          additionalProperties:
            type: string
        errorCode:
          title: ErrorCode
          description: 'Machine-parsable classification of the error. Always set on responses generated by the global

            exception handler. Branch your own error handling on this (not the message text).'
          type: string
          enum:
          - BadRequest
          - Unauthorized
          - PaymentRequired
          - Forbidden
          - NotFound
          - MethodNotAllowed
          - Conflict
          - PayloadTooLarge
          - Validation
          - RateLimited
          - InternalError
        requestId:
          description: Per-request correlation ID. Include this when contacting support so we can find the request in our logs.
          type: string
    PublicApiIncomingWebhookResponse:
      title: PublicApiIncomingWebhookResponse
      type: object
      required:
      - data
      properties:
        data:
          title: PublicApiIncomingWebhook
          type: object
          required:
          - id
          - createdDate
          - createdBy
          - updatedDate
          - updatedBy
          - workflowId
          - name
          - automationApp
          - status
          - url
          - config
          properties:
            id:
              title: EntityID
              description: The resource's ID.
              type: string
            createdDate:
              description: When the resource was first created. ISO-8601 UTC.
              type: string
              format: date-time
            createdBy:
              description: User who created the resource.
              examples:
              - id: iAaSNCU5lWLYGAi663hO8Q
                email: jane.doe@example.com
                username: Jane Doe
              type: object
              required:
              - id
              - email
              - username
              properties:
                id:
                  title: EntityID
                  description: The resource's ID.
                  type: string
                email:
                  description: The user's email address (also their login identifier).
                  type: string
                username:
                  description: The user's display name (e.g. `Jane Doe`).
                  type: string
            updatedDate:
              description: When the resource was last modified. ISO-8601 UTC.
              type: string
              format: date-time
            updatedBy:
              description: User who last modified the resource.
              examples:
              - id: iAaSNCU5lWLYGAi663hO8Q
                email: jane.doe@example.com
                username: Jane Doe
              type: object
              required:
              - id
              - email
              - username
              properties:
                id:
                  title: EntityID
                  description: The resource's ID.
                  type: string
                email:
                  description: The user's email address (also their login identifier).
                  type: string
                username:
                  description: The user's display name (e.g. `Jane Doe`).
                  type: string
            workflowId:
              description: The ID of the Workflow
              examples:
              - ucBWWop27GXEGmStvtRH_Q
              type: string
            name:
              description: Human-readable label for the webhook (e.g. "Salesforce → Onboarding").
              type: string
            automationApp:
              description: Label of the automation app or integration source (e.g. `Zapier`, `Custom`, `Salesforce`).
              type: string
            status:
              description: Whether the incoming webhook is currently accepting payloads. `Active` — incoming requests at the webhook URL create or update a workflow run. `Disabled` — the webhook URL is configured but requests are ignored.
              type: string
              enum:
              - Active
              - Disabled
            url:
              description: Public URL to POST payloads to. Include this in the upstream system's webhook config.
              type: string
            config:
              title: PublicApiIncomingWebhookConfig
              description: Field-specific configuration. Shape depends on `fieldType`.
              type: object
              required:
              - properties
              - formFields
              properties:
                properties:
                  description: Mapping from workflow-run property names (e.g. `Name`, `DueDate`, `Assignees`) to JSONPath expressions in the incoming payload.
                  type: object
                  additionalProperties:
                    type: string
                formFields:
                  description: Mapping from form-field IDs to JSONPath expressions in the incoming payload.
                  type: object
                  additionalProperties:
                    type: string
            links:
              description: Navigable HATEOAS links to related resources. Each entry has a `name` (RFC-5988 link relation like `self`, `edit`, `related`), an `href` URL, and a `type` (`Api` for callable endpoints, `App` for browser-facing URLs). Prefer following these `href` values over constructing URLs by hand.
              type: array
              items:
                title: Link
                description: A HATEOAS link to a related resource. Use these to navigate between resources without constructing URLs by hand.
                type: object
                required:
                - name
                - href
                - type
                properties:
                  name:
                    description: Standard link relation name (RFC 5988) indicating this link's role. Common values include `self`, `edit`, `related`, `previous`, `next`.
                    type: string
                  href:
                    title: Uri
                    description: URL of the linked resource.
                    examples:
                    - https://api.process.st/api/v1.1/resource/XXX
                    type: string
                  rel:
                    description: Optional. The kind of resource this link points to (e.g. `Workflow`, `Task`, `Comment`).
                    type: string
                    enum:
                    - Approval Task
                    - Approvals
                    - Assignees
                    - Comment
                    - Data Set Records
                    - Data Sets
                    - Form Field Values
                    - Subject Task
                    - Task
                    - Tasks
                    - Users
                    - Webhook
                    - Workflow
                    - Workflow Run
                  type:
                    description: Whether this link targets an API endpoint or a Process Street app URL. `Api` — a callable API endpoint you can fetch directly. `App` — a browser-facing URL in the Process Street UI.
                    type: string
                    enum:
                    - Api
                    - App
        links:
          description: 'Pagination links. When the result has more pages, look for an entry with `name: "next"` — its `href` is the URL to fetch the next page. Absence of `next` means there are no more pages. For single-resource responses this array is typically empty.'
          type: array
          items:
            title: Link
            description: A HATEOAS link to a related resource. Use these to navigate between resources without constructing URLs by hand.
            type: object
            required:
            - name
            - href
            - type
            properties:
              name:
                description: Standard link relation name (RFC 5988) indicating this link's role. Common values include `self`, `edit`, `related`, `previous`, `next`.
                type: string
              href:
                title: Uri
                description: URL of the linked resource.
                examples:
                - https://api.process.st/api/v1.1/resource/XXX
                type: string
              rel:
                description: Optional. The kind of resource this link points to (e.g. `Workflow`, `Task`, `Comment`).
                type: string
                enum:
                - Approval Task
                - Approvals
                - Assignees
                - Comment
                - Data Set Records
                - Data Sets
                - Form Field Values
                - Subject Task
                - Task
                - Tasks
                - Users
                - Webhook
                - Workflow
                - Workflow Run
              type:
                description: Whether this link targets an API endpoint or a Process Street app URL. `Api` — a callable API endpoint you can fetch directly. `App` — a browser-facing URL in the Process Street UI.
                type: string
                enum:
                - Api
                - App
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    httpAuth:
      type: http
      description: Bearer token (beta)
      scheme: bearer
x-tagGroups:
- name: Workflows
  tags:
  - Workflows
  - Workflow Revisions
  - Form Fields
  - Workflow Logic Rules
  - Workflow Tasks
  - Workflow Task Assignment Rules
  - Workflow Widgets
  - Workflow Due Date Rules
  - Workflow Task Due Date Rules
  - Workflow Incoming Webhooks
  - Scheduled Workflows
- name: Workflow Runs
  tags:
  - Workflow Runs
  - Tasks
  - Form Field Values
  - Comments
  - Attachments
- name: Pages
  tags:
  - Pages
  - Page Revisions
  - Page Widgets
- name: Data Sets
  tags:
  - Data Sets
  - Data Set Incoming Webhooks
- name: Other
  tags:
  - Folders
  - One-Off Tasks
  - Users
  - Webhooks
  - File Uploads
  - Utilities
  - My Work