openapi: 3.2.0
info:
  title: Loopio Webhooks API
  description: Loopio's Public API
  termsOfService: http://loopio.com/termsOfService
  contact:
    email: support@loopio.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
- url: https://api.loopio.com/data/v2
  description: Production server for the American datacenter
- url: https://api.eu.loopio.com/data/v2
  description: Production server for the European datacenter
tags:
- name: Webhooks
  description: Create & Manage webhook subscriptions
paths:
  /webhookSubscriptions:
    get:
      tags:
      - Webhooks
      summary: List your event subscriptions (webhooks)
      operationId: listWebhookSubscriptions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookSubscription'
        '403':
          $ref: '#/components/responses/403'
      security:
      - loopio_auth:
        - webhook:read
    post:
      tags:
      - Webhooks
      summary: Create a new event subscription (new webhook)
      description: 'Callback URL validation as described [here](https://support.loopio.com/hc/en-us/articles/4404035824147-How-Do-I-Validate-My-Webhook-URL-) will occur automatically as part of this request.

        Help with handling webhook callback requests can be found [here](https://support.loopio.com/hc/en-us/articles/4404035409555-What-Information-is-in-a-Webhook-Event-Notification-)'
      operationId: createWebhookSubscription
      requestBody:
        required: true
        description: Subscription details
        content:
          application/json:
            schema:
              type: object
              properties:
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/SubscribableEvent'
                  minItems: 1
                webhookUrl:
                  type: string
                  format: uri
                  pattern: ^https://
              required:
              - events
              - webhookUrl
      responses:
        '201':
          description: CREATED
          headers:
            Location:
              description: URL of the created webhook subscription
              required: true
              schema:
                type: string
                format: uri
                pattern: ^(http|https)://
              example: https://api.loopio.com/data/v2/webhookSubscriptions/123
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                name: VALIDATION_ERROR
                message: Invalid webhook url
                debugId: 0fas5
        '403':
          $ref: '#/components/responses/403'
      callbacks:
        LibraryEntryUpdated:
          $ref: '#/components/callbacks/LibraryEntryUpdated'
        LibraryReviewAssigned:
          $ref: '#/components/callbacks/LibraryReviewAssigned'
        ProjectStatusUpdated:
          $ref: '#/components/callbacks/ProjectStatusUpdated'
        ProjectCreated:
          $ref: '#/components/callbacks/ProjectCreated'
      security:
      - loopio_auth:
        - webhook:write
  /webhookSubscriptions/{subscriptionId}:
    parameters:
    - $ref: '#/components/parameters/SubscriptionId'
    get:
      tags:
      - Webhooks
      summary: Get event subscription details
      operationId: getWebhookSubscription
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
      security:
      - loopio_auth:
        - webhook:read
    put:
      tags:
      - Webhooks
      summary: Change event subscription details
      operationId: updateWebhookSubscription
      requestBody:
        required: true
        description: Update a webhook. Setting the status to ACTIVE will trigger a callback validation
        content:
          application/json:
            schema:
              type: object
              properties:
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/SubscribableEvent'
                  minLength: 1
                webhookUrl:
                  type: string
                  format: uri
                  pattern: ^https://
                status:
                  type: string
                  enum:
                  - ACTIVE
                  - DISABLED
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
      security:
      - loopio_auth:
        - webhook:write
    delete:
      tags:
      - Webhooks
      summary: Cancel an event subscription
      operationId: cancelWebhookSubscription
      responses:
        '204':
          $ref: '#/components/responses/204'
      security:
      - loopio_auth:
        - webhook:delete
  /webhookSubscriptions/{subscriptionId}/signingSecret:
    parameters:
    - $ref: '#/components/parameters/SubscriptionId'
    post:
      tags:
      - Webhooks
      summary: Refresh a webhook's signing secret to a new value
      operationId: refreshWebhookSigningSecret
      responses:
        '201':
          description: CREATED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
      security:
      - loopio_auth:
        - webhook:write
components:
  callbacks:
    LibraryEntryUpdated:
      '{$request.body#/webhookUrl}':
        post:
          summary: Library Entry Updated
          description: 'Sent whenever a Library Entry is manually updated by a user.

            This includes editing an entry, reviewing an entry, bulk actions, and search & replace.

            '
          parameters:
          - $ref: '#/components/parameters/WebhookContentSignature'
          - $ref: '#/components/parameters/WebhookTimestamp'
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    event:
                      type: string
                      enum:
                      - libraryEntry.updated
                    context:
                      type: object
                      properties:
                        libraryEntryIds:
                          type: array
                          items:
                            type: integer
                  required:
                  - event
                  - context
          responses:
            '200':
              description: OK
    ProjectCreated:
      '{$request.body#/webhookUrl}':
        post:
          summary: Project Created
          description: Sent whenever a Project is created.
          parameters:
          - $ref: '#/components/parameters/WebhookContentSignature'
          - $ref: '#/components/parameters/WebhookTimestamp'
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    event:
                      type: string
                      enum:
                      - project.created
                    context:
                      type: object
                      properties:
                        projectId:
                          type: number
                      required:
                      - projectId
                  required:
                  - event
                  - context
          responses:
            '200':
              description: OK
    ProjectStatusUpdated:
      '{$request.body#/webhookUrl}':
        post:
          summary: Project Status Updated
          description: Sent whenever a Project status has been updated
          parameters:
          - $ref: '#/components/parameters/WebhookContentSignature'
          - $ref: '#/components/parameters/WebhookTimestamp'
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    event:
                      type: string
                      enum:
                      - project.statusChanged
                    context:
                      type: object
                      properties:
                        projectId:
                          type: number
                        status:
                          type: string
                          enum:
                          - ACTIVE
                          - COMPLETE
                          - DELETED
                          - STOPPED
                          - DONE
                          - WON
                          - LOST
                  required:
                  - event
                  - payload
          responses:
            '200':
              description: OK
    LibraryReviewAssigned:
      '{$request.body#/webhookUrl}':
        post:
          summary: Library Review Assigned
          description: Sent whenever a Library Review is created and assigned to someone
          parameters:
          - $ref: '#/components/parameters/WebhookContentSignature'
          - $ref: '#/components/parameters/WebhookTimestamp'
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    event:
                      type: string
                      enum:
                      - libraryReview.assigned
                    context:
                      type: object
                      properties:
                        libraryEntryId:
                          type: number
                        reviewId:
                          type: number
                        asignedTo:
                          type: object
                        assignedBy:
                          oneOf:
                          - type: object
                            properties:
                              type:
                                type: string
                                enum:
                                - user
                              id:
                                type: number
                              email:
                                type: string
                            required:
                            - type
                            - id
                            - email
                          - type: object
                            properties:
                              type:
                                type: string
                                enum:
                                - automated_process
                            required:
                            - type
                        dueDate:
                          type:
                          - string
                          - 'null'
                          format: date-time
                  required:
                  - event
                  - payload
                  - dueDate
          responses:
            '200':
              description: OK
  parameters:
    WebhookTimestamp:
      in: header
      name: X-Loopio-Request-Timestamp
      description: Timestamp of when the request was sent
      schema:
        type: integer
      required: true
    SubscriptionId:
      name: subscriptionId
      in: path
      required: true
      schema:
        type: integer
    WebhookContentSignature:
      in: header
      name: X-Loopio-Content-Signature
      description: The JSON-encoded body of the request, hashed by the Webhook's signing secret. See [here](https://support.loopio.com/hc/en-us/articles/4404073215763-How-Do-I-Use-My-Signing-Secret-) for more information.
      schema:
        type: string
      required: true
  schemas:
    SubscribableEvent:
      type: string
      enum:
      - libraryEntry.updated
      - libraryReview.assigned
      - project.statusChanged
      - project.created
    Error:
      type: object
      properties:
        name:
          type: string
          enum:
          - FATAL_ERROR
          - FORBIDDEN
          - INVALID_REQUEST
          - NO_PERMISSION
          - RESOURCE_NOT_FOUND
          - UNPROCESSABLE_REQUEST
          - VALIDATION_ERROR
        message:
          type: string
        debugId:
          type: string
    WebhookSubscription:
      type: object
      properties:
        id:
          type: integer
        webhookUrl:
          type: string
          format: uri
          pattern: ^https://
        events:
          type: array
          items:
            $ref: '#/components/schemas/SubscribableEvent'
          minItems: 1
        status:
          type: string
          enum:
          - PENDING
          - ACTIVE
          - DISABLED
        creator:
          type: object
          properties:
            id:
              type: integer
          required:
          - id
      required:
      - id
      - webhookUrl
      - events
      - status
      - creator
  responses:
    '400':
      description: Invalid Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            name: INVALID_REQUEST
            message: Bad request
            debugId: 0fas3
    '403':
      description: No Permission
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            name: NO_PERMISSION
            message: No permission to access the resource
            debugId: 0fas3
    '204':
      description: No Content
    '404':
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            name: RESOURCE_NOT_FOUND
            message: Resource not found
            debugId: 0fas3
  securitySchemes:
    loopio_auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth2/authorize
          tokenUrl: /oauth2/access_token
          scopes:
            mergeVariable:read: View Merge Variables
            mergeVariable:write: Create/Edit Merge Variables
            mergeVariable:delete: Delete Merge Variables
            crm:read: List CRM opportunities linked to projects
            crm:write: Link CRM opportunities to projects
            customer.info:read: View customer information
            file:read: Download files and view file information
            file:delete: Delete files
            library:read: List Library Entries and stacks, view Library Entries and Entry data
            library:write: Create and update Library Entries and Entry data
            library:delete: Delete Library Entries
            project:read: List Projects, view Project data and source documents
            project:write: Create and update Projects, Project data, and source documents
            project:delete: Delete a Project
            project.participant:read: List participants of a project
            project.participant:write: Update participant information
            role:read: List user assignable roles
            user:read: List users, view user information
            user:write: Update user information
            webhook:read: View webhook subscriptions
            webhook:write: Create & edit webhook subscriptions
            webhook:delete: Delete webhook subscriptions
        clientCredentials:
          tokenUrl: /oauth2/access_token
          scopes:
            mergeVariable:read: View Merge Variables
            mergeVariable:write: Create/Edit Merge Variables
            mergeVariable:delete: Delete Merge Variables
            crm:read: List CRM opportunities linked to projects
            crm:write: Link CRM opportunities to projects
            customer.info:read: View customer information
            file:read: Download files and view file information
            file:delete: Delete files
            library:read: List Library Entries and stacks, view Library Entries and Entry data
            library:write: Create and update Library Entries and Entry data
            library:delete: Delete Library Entries
            project:read: List Projects, view Project data and source documents
            project:write: Create and update Projects, Project data, and source documents
            project:delete: Delete a Project
            project.participant:read: List participants of a project
            project.participant:write: Update participant information
            role:read: List user assignable roles
            user:read: List users, view user information
            user:write: Update user information
            webhook:read: View webhook subscriptions
            webhook:write: Create & edit webhook subscriptions
            webhook:delete: Delete webhook subscriptions