openapi: 3.2.0
info:
  version: 1.0.0
  title: Paperform Webhooks API
  contact:
    name: Paperform API Support
    url: https://paperform.co
    email: support@paperform.co
servers:
- url: https://api.paperform.co/v1
security:
- bearerAuth: []
tags:
- name: Webhooks
paths:
  /forms/{slug_or_id}/webhooks:
    get:
      parameters:
      - $ref: '#/components/parameters/slugOrID'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/afterId'
      - $ref: '#/components/parameters/beforeId'
      - $ref: '#/components/parameters/beforeDate'
      - $ref: '#/components/parameters/afterDate'
      - $ref: '#/components/parameters/sort'
      description: 'This endpoint returns a list of webhooks for a form that are accessible by the authorized user.

        Please note that this feature is exclusively available as part of the Business API.'
      operationId: listFormWebhooks
      tags:
      - Webhooks
      responses:
        '200':
          description: Successfully returned a list of webhooks for a form
          content:
            application/json:
              schema:
                type: object
                allOf:
                - properties:
                    status:
                      type: string
                      enum:
                      - ok
                    results:
                      type: object
                      properties:
                        webhooks:
                          type: array
                          items:
                            $ref: '#/components/schemas/Webhook'
                - $ref: '#/components/schemas/Pagination'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/Throttled'
        5XX:
          $ref: '#/components/responses/Unexpected'
      summary: List form webhooks
      x-summary-source: derived
    post:
      parameters:
      - $ref: '#/components/parameters/slugOrID'
      description: 'This endpoint creates a specific webhook on a form.

        Please note that this feature is exclusively available as part of the Business API.'
      operationId: createFormWebhook
      tags:
      - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhook'
              required:
              - target_url
              - triggers
      responses:
        '200':
          description: 'Successfully created a single webhook with the provided values

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                  results:
                    type: object
                    properties:
                      webhook:
                        $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Validation'
        '429':
          $ref: '#/components/responses/Throttled'
        5XX:
          $ref: '#/components/responses/Unexpected'
      summary: Create form webhook
      x-summary-source: derived
  /webhooks/{id}:
    get:
      parameters:
      - $ref: '#/components/parameters/webhookID'
      description: 'This endpoint returns a webhook for a form by ID.

        Please note that this feature is exclusively available as part of the Business API.'
      operationId: getFormWebhook
      tags:
      - Webhooks
      responses:
        '200':
          description: Successfully returned a webhook for a form by ID
          content:
            application/json:
              schema:
                type: object
                allOf:
                - properties:
                    status:
                      type: string
                      enum:
                      - ok
                    results:
                      type: object
                      properties:
                        webhook:
                          $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/Throttled'
        5XX:
          $ref: '#/components/responses/Unexpected'
      summary: Get form webhook
      x-summary-source: derived
    put:
      parameters:
      - $ref: '#/components/parameters/webhookID'
      description: 'This endpoint updates a specific webhook on a form.

        Please note that this feature is exclusively available as part of the Business API.'
      operationId: updateFormWebhook
      tags:
      - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhook'
      responses:
        '200':
          description: 'Successfully updated a single webhook with the provided values

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                  results:
                    type: object
                    properties:
                      webhook:
                        $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Validation'
        '429':
          $ref: '#/components/responses/Throttled'
        5XX:
          $ref: '#/components/responses/Unexpected'
      summary: Update form webhook
      x-summary-source: derived
    delete:
      parameters:
      - $ref: '#/components/parameters/webhookID'
      description: 'This endpoint deletes a specific webhook by ID.

        Please note that this feature is exclusively available as part of the Business API.'
      operationId: deleteFormWebhook
      tags:
      - Webhooks
      responses:
        '200':
          description: 'Successfully deleted a single webhook that matched the provided ID

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/Throttled'
        5XX:
          $ref: '#/components/responses/Unexpected'
      summary: Delete form webhook
      x-summary-source: derived
components:
  responses:
    Throttled:
      description: Too Many Requests
      content:
        text/html:
          schema:
            type: string
            enum:
            - Too many requests.
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - authentication
                  description: Token not provided for not valid.
    Forbidden:
      description: Not Permitted
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - permission
                  description: Not permitted to access requested resource.
    Validation:
      description: Validation Error
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - validation
                  description: Invalid parameters provided.
    BadRequest:
      description: Invalid Request
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - validation
                  description: Invalid parameters provided.
    Unexpected:
      description: Unexpected Error
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - server_error
                  description: An unexpected error.
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - not_found
                  description: The requested resource was not found.
  schemas:
    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The id of the webhook.
          readOnly: true
        target_url:
          type: string
          format: url
          example: https://example.com/webhook
          description: The url for the webhook.
        triggers:
          type: array
          description: The triggers for the webhook.
          example:
          - submission
          items:
            type: string
            enum:
            - submission
            - partial_submission
        created_at:
          type: string
          format: date-time
          description: A formatted date-time string in your account timezone indicating the time the webhook was created.
          example: '2018-01-01T12:00:00Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: A formatted date-time string in your account timezone indicating the time the webhook was last updated.
          example: '2018-01-01T12:00:00Z'
          readOnly: true
        account_timezone:
          type: string
          description: The timezone of your account.
          example: America/Los_Angeles
          readOnly: true
        created_at_utc:
          type: string
          format: date-time
          description: A formatted date-time string in UTC timezone indicating the time the webhook was created.
          example: '2018-01-01T12:00:00Z'
          readOnly: true
        updated_at_utc:
          type: string
          format: date-time
          description: A formatted date-time string in UTC timezone indicating the time the webhook was last updated.
          example: '2018-01-01T12:00:00Z'
          readOnly: true
    Pagination:
      type: object
      properties:
        total:
          type: integer
          description: The total number of items.
          readOnly: true
          example: 57
        has_more:
          description: Whether there are more items.
          type: boolean
          example: true
          readOnly: true
        limit:
          description: The limit of items per page.
          type: integer
          example: 20
          default: 20
        skip:
          description: The number of items to skip.
          type: integer
          default: 0
          example: 0
    Error:
      type: object
      properties:
        status:
          type: string
          enum:
          - error
          example: error
        message:
          type: string
          description: An error message.
          example: Invalid request
        details:
          type: array
          description: Suggested actions to resolve the error.
          items:
            type: string
  parameters:
    slugOrID:
      in: path
      name: slug_or_id
      required: true
      schema:
        type: string
      description: The form's slug, custom slug or ID.
      example: my-form-slug
    beforeDate:
      in: query
      name: before_date
      schema:
        type: string
        format: date-time
      description: Return results created on or after this date-time (UTC). Overwritten by `before_id`.
      example: '2019-06-11T20:36:29Z'
    afterDate:
      in: query
      name: after_date
      schema:
        type: string
        format: date-time
      description: Return results created before this date (UTC). Overwritten by `after_id`.
      example: '2019-06-11T20:36:29Z'
    skip:
      in: query
      name: skip
      schema:
        type: integer
        default: 0
      description: Number of results to skip in the result set.
    sort:
      in: query
      name: sort
      schema:
        type: string
        enum:
        - ASC
        - DESC
        default: DESC
      description: The direction to sort in. Results are sorted by `created_at`, and defaults to `"DESC"`.
      example: ASC
    webhookID:
      in: path
      required: true
      name: id
      schema:
        type: string
      description: The ID of the webhook to get results for.
      example: 5d40fdaf174b4c0007043072
    limit:
      in: query
      name: limit
      schema:
        type: integer
        maximum: 100
        default: 20
      description: The number or results to return.
    afterId:
      in: query
      name: after_id
      schema:
        type: string
      description: Return results after the provided ID.
      example: 5d40fdaf174b4c0007043072
    beforeId:
      in: query
      name: before_id
      schema:
        type: string
      description: Return results before the provided ID.
      example: 5d40fdaf174b4c0007043072
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-readme:
  explorer-enabled: true
  proxy-enabled: true