print-one Webhooks API

openapi: 3.2.0
info:
  title: Print.one Webhooks API
  description: 'This documentation belongs to Print.one''s API. # Introduction

    This API is documented in **OpenAPI format**. In addition to standard

    OpenAPI syntax we use a few vendor extensions


    For technical information about our API, please consult our help center or request support. # Cross-Origin Resource Sharing

    This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec. And that allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site. # Authentication


    # Early Access

    Some features are marked as ''Early Access''. This means only a small portion of users have access to these features. We do this to conduct thorough testing before a major release. Would you like to gain access to one of our Early Access features? Please raise a >">support ticket here, specifying which feature you would like access to. # Premium Access

    Some features are marked as ''Premium''. This means this feature is only included on paid plans. Would you like to gain access to one of our Premium features? Have a look at the Subscriptions page. # API Errors

    Below is a list with all known errors returned by our API, identified by a unique `code`. These codes will also show in the error response of specific API responses. Unique code

    Error name

    Error type

    Example message


    10001

    InvalidInputData

    Combined

    Invalid input data


    10002

    OrderPropertyRequired

    Default

    The property recipient is required


    10003

    OrderCreationError

    Combined

    Could not create order


    10004

    RecipientAddressInvalid

    Default

    Recipient''s address is invalid


    10005

    AddressValidation

    Validation

    Address validation failed


    10006

    ResourceNotFound

    Default

    Campaign ''cmp_123456789'' does not exist


    10007

    BatchWrongMode

    Default

    Batch is ''live'', but received a ''live'' request


    10008

    BatchNotAcceptingOrders

    Default

    Batch ''batch_123456789'' is not in a state to accept orders


    10009

    BatchIsFull

    Default

    Batch ''batch_123456789'' is full and does not accept any more orders (max 10000 orders per batch)


    10010

    ArchivedCampaignNotAcceptingOrders

    Default

    Campaign ''My Campaign'' is archived and no longer accepts orders


    10011

    ProductFeatureNotAllowed

    Default

    The product ''GREETINGCARD_SQ15'' does not support batch


    10012

    ObjectMissingRequiredFields

    Default

    The recipient is missing required fields


    10013

    CannotRetrieveObject

    Default

    An error occurred while retrieving the design ''tmpl_123456798''


    10014

    DesignContentUnparsable

    Combined

    Could not parse the design content


    10015

    FormatPageRequirement

    Default

    The format ''POSTCARD_A5'' requires 2 pages, but 1 was provided


    10016

    DuplicateDesignPage

    Default

    Found page ''1'' multiple times in the design


    10017

    CountryNotSupported

    Default

    The country ''BE'' is not supported


    10018

    ProductDestinationNotAllowed

    Default

    The product ''GREETINGCARD_SQ15'' does not support GERMANY


    10019

    UnknownCreationError

    Default

    An unknown error occurred while creating the campaign


    10020

    UnknownPublishError

    Default

    An unknown error occurred while publishing the order


    10021

    SendDateInPast

    Default

    The send date must be in the future


    10022

    SendDateBeyondYear

    Default

    The send date must be within one year


    10023

    InstallNotAllowed

    Default

    You are not allowed to install this integration


    10024

    BatchRecipientCountryRestriction

    Default

    Only addresses shipped to ''NL'' are allowed for this batch


    10025

    PostalStampCountryUnavailable

    Default

    Postal stamp ''stmp_123456789'' is not available for the country ''BE''


    10026

    EarlyAccessRestricted

    Default

    Sorry, some-early-access-feature is in early access.'
  version: v3
  contact:
    name: Print.one
    url: https://support.print.one
    email: info@print.one
servers:
- url: https://api.print.one
tags:
- name: Webhooks
  description: Webhooks report system updates to your own systems.
  v3:
    x-premiumAccess: true
  x-premiumAccess: true
paths:
  /v3/webhooks:
    post:
      operationId: Webhook/createWebhook
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateV3WebhookRequestDto'
      responses:
        '201':
          description: The created webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ResponseDto'
        '403':
          description: Request has invalid grant scope, missing one of (<code>own.webhooks.create, all.webhooks.create</code>)
      security:
      - API Key: []
      - Oauth2:
        - webhooks.write
        - tenant.admin
        - live.api.key
      tags:
      - Webhooks
      summary: Webhook/create webhook
      x-summary-source: derived
    get:
      operationId: Webhook/getWebhooks
      parameters: []
      responses:
        '200':
          description: Get a list of webhook logs
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedDocumented'
                - properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/GetV3WebhookResponseDto'
                    meta:
                      properties:
                        select:
                          type: array
                          items:
                            type: string
                        filter:
                          type: object
                          properties: {}
        '400':
          description: The provided pagination query was incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse6a1ea2613cf2c41bb65e6b9eb34bea04f7ba0c4ac3abeec93be5a78e665f2d6b'
        '403':
          description: Request has invalid grant scope, missing one of (<code>own.webhooks.read</code>)
      security:
      - API Key: []
      - Oauth2:
        - webhooks.read
        - live.api.key
      tags:
      - Webhooks
      summary: Webhook/get webhooks
      x-summary-source: derived
  /v3/webhooks/{id}:
    get:
      operationId: Webhook/getWebhook
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: The requested webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ResponseDto'
        '403':
          description: Request has invalid grant scope, missing one of (<code>own.webhooks.read</code>)
      security:
      - API Key: []
      - Oauth2:
        - webhooks.read
        - live.api.key
      tags:
      - Webhooks
      summary: Webhook/get webhook
      x-summary-source: derived
    patch:
      operationId: Webhook/updateWebhook
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateV3WebhookRequestDto'
      responses:
        '200':
          description: The updated webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ResponseDto'
        '403':
          description: Request has invalid grant scope, missing one of (<code>own.webhooks.write</code>)
      security:
      - API Key: []
      - Oauth2:
        - webhooks.write
        - live.api.key
      tags:
      - Webhooks
      summary: Webhook/update webhook
      x-summary-source: derived
    delete:
      operationId: Webhook/deleteWebhook
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: The webhook was successfully deleted
        '403':
          description: Request has invalid grant scope, missing one of (<code>own.webhooks.delete, all.webhooks.delete</code>)
      security:
      - API Key: []
      - Oauth2:
        - webhooks.write
        - tenant.admin
        - live.api.key
      tags:
      - Webhooks
      summary: Webhook/delete webhook
      x-summary-source: derived
  /v3/webhooks/{id}/logs:
    get:
      operationId: Webhook/getWebhookLogs
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: "Page number to retrieve. If you provide an invalid value the default page number will be applied'\n        <p>\n             <b>Default Value: </b> 1\n          </p>\n        "
        schema:
          example: 1
          type: number
      - name: limit
        required: false
        in: query
        description: "Number of records per page.\n      <p>\n             <b>Default Value: </b> 20\n          </p>\n      <p>\n             <b>Max Value: </b> 200\n          </p>\n      <i><b>If provided value is greater than max value, max value will be applied.</b></i>\n      "
        schema:
          example: 20
          type: number
      - name: filter.event
        required: false
        in: query
        description: "Filter by event query param.\n          <p>\n             <b>Format: </b> filter.event={$not}:OPERATION:VALUE\n          </p>\n          <h4><b>Available Operations:</b></h4><ul><li>$eq</li><li>$in</li><li>$not</li></ul>"
        schema:
          example: $eq:value
          type: string
      - name: filter.status
        required: false
        in: query
        description: "Filter by status query param.\n          <p>\n             <b>Format: </b> filter.status={$not}:OPERATION:VALUE\n          </p>\n          <h4><b>Available Operations:</b></h4><ul><li>$eq</li><li>$not</li></ul>"
        schema:
          example: $eq:value
          type: string
      - name: filter.createdAt
        required: false
        in: query
        description: "Filter by createdAt query param.\n          <p>\n             <b>Format: </b> filter.createdAt=OPERATION:VALUE\n          </p>\n          <h4><b>Available Operations:</b></h4><ul><li>$gte</li><li>$gt</li><li>$btw</li><li>$lt</li><li>$lte</li></ul>"
        schema:
          example: $gte:value
          type: string
      - name: sortBy
        required: false
        in: query
        description: "Parameter to sort by.\n      <p>To sort by multiple fields, just provide query param multiple types. The order in url defines an order of sorting</p>\n      <p>\n             <b>Format: </b> fieldName:DIRECTION\n          </p>\n      <p>\n             <b>Default Value: </b> createdAt:DESC\n          </p>\n      <h4><b>Available Fields:</b></h4><ul><li>createdAt</li></ul>\n      "
        schema:
          example: id:DESC,createdAt:ASC
          type: array
          items:
            type: string
      responses:
        '200':
          description: Get a list of webhook logs
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedDocumented'
                - properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/GetV3WebhookLogsResponseDto'
                    meta:
                      properties:
                        select:
                          type: array
                          items:
                            type: string
                        filter:
                          type: object
                          properties:
                            webhookId:
                              oneOf:
                              - type: string
                              - type: array
                                items:
                                  type: string
                            event:
                              oneOf:
                              - type: string
                              - type: array
                                items:
                                  type: string
                            status:
                              oneOf:
                              - type: string
                              - type: array
                                items:
                                  type: string
                            createdAt:
                              oneOf:
                              - type: string
                              - type: array
                                items:
                                  type: string
        '400':
          description: The provided pagination query was incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse6a1ea2613cf2c41bb65e6b9eb34bea04f7ba0c4ac3abeec93be5a78e665f2d6b'
        '403':
          description: Request has invalid grant scope, missing one of (<code>own.webhooks.read</code>)
      security:
      - API Key: []
      - Oauth2:
        - webhooks.read
        - live.api.key
      tags:
      - Webhooks
      summary: Webhook/get webhook logs
      x-summary-source: derived
components:
  schemas:
    GetV3WebhookResponseDto:
      type: object
      properties:
        id:
          type: string
          description: The id of the webhook
        name:
          type: string
          description: The custom name of the webhook
          example: Production - Order Updates
        url:
          type: string
          description: The callback of the webhook
          example: https://api.print.one/some-webhook-callback
        active:
          type: boolean
          description: Whether the webhook is active
          example: true
        events:
          type: array
          description: List of events to subscribe to
          items:
            type: string
            enum:
            - order_status_update
            - template_preview_rendered
            - coupon_code_used
            - qr_code_scanned
            - mailing_sent
        headers:
          type: object
          description: A map of headers to add to each webhook call
          example:
            CustomEvent: this-is-a-test
        secretHeaders:
          type: object
          description: A map of headers with secret values
          example:
            Authorization: '** SecretValue **'
        successRate:
          type: object
          description: Percentage of calls to the webhook that have been successful
          example: 62
        filters:
          description: Applied filters
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/SingularV3WebhookFilter'
            - $ref: '#/components/schemas/PluralV3WebhookFilter'
      required:
      - id
      - name
      - url
      - active
      - events
      - headers
      - secretHeaders
      - successRate
    PaginatedMetaDocumented:
      type: object
      properties:
        itemsPerPage:
          type: number
          title: Number of items per page
        totalItems:
          type: number
          title: Total number of items
        currentPage:
          type: number
          title: Current requested page
        totalPages:
          type: number
          title: Total number of pages
        sortBy:
          type: array
          title: Sorting by columns
          items:
            type: array
            items:
              oneOf:
              - type: string
              - type: string
                enum:
                - ASC
                - DESC
        searchBy:
          title: Search by fields
          type: array
          items:
            type: string
        search:
          type: string
          title: Search term
        filter:
          type: object
          title: Filters that applied to the query
          required: []
          properties: {}
        filterOptions:
          type: object
          title: Filters that applied to the query
          required: []
          properties: {}
      required:
      - itemsPerPage
      - totalItems
      - currentPage
      - totalPages
    PluralV3WebhookFilter:
      type: object
      properties:
        key:
          type: string
          description: The key to compare against
          example: status
        event:
          type: string
          description: The event the filter should apply on
          example: order_status_update
          enum:
          - order_status_update
          - template_preview_rendered
          - coupon_code_used
          - qr_code_scanned
          - mailing_sent
        type:
          type: string
          enum:
          - in
          - not-in
          example: not-in
        value:
          description: The values to compare against
          example:
          - order_failed
          - order_cancelled
          type: array
          items:
            type: string
      required:
      - key
      - event
      - type
      - value
    UpdateV3WebhookRequestDto:
      type: object
      properties:
        name:
          type: string
          description: The custom name of the webhook
          example: Production - Order Updates
        url:
          type: string
          description: The callback of the webhook
          example: https://api.print.one/some-webhook-callback
        active:
          type: boolean
          description: Whether the webhook is active
          example: true
        headers:
          type: object
          description: A map of headers to add to each webhook call
          example:
            CustomEvent: this-is-a-test
        secretHeaders:
          type: object
          description: A map of headers with secret values, which will not be visible after saving
          example:
            Authorization: Basic user:password
        events:
          type: array
          description: List of events to subscribe to
          items:
            type: string
            enum:
            - order_status_update
            - template_preview_rendered
            - coupon_code_used
            - qr_code_scanned
            - mailing_sent
        filters:
          description: Applied filters
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/SingularV3WebhookFilter'
            - $ref: '#/components/schemas/PluralV3WebhookFilter'
    PaginatedLinksDocumented:
      type: object
      properties:
        first:
          type: string
          title: Link to first page
          nullable: true
        previous:
          type: string
          title: Link to previous page
          nullable: true
        current:
          type: string
          title: Link to current page
        next:
          type: string
          title: Link to next page
          nullable: true
        last:
          type: string
          title: Link to last page
          nullable: true
      required:
      - current
    ErrorResponse6a1ea2613cf2c41bb65e6b9eb34bea04f7ba0c4ac3abeec93be5a78e665f2d6b:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 400
        message:
          description: Error messages
          examples:
          - - Invalid paginated query provided
          type: array
          items:
            type: string
      required:
      - statusCode
      - message
    V3ResponseDto:
      type: object
      properties:
        data:
          type: object
      required:
      - data
    CreateV3WebhookRequestDto:
      type: object
      properties:
        name:
          type: string
          description: The custom name of the webhook
          example: Production - Order Updates
        url:
          type: string
          description: The callback of the webhook
          example: https://api.print.one/some-webhook-callback
        active:
          type: boolean
          description: Whether the webhook is active
          example: true
        headers:
          type: object
          description: A map of headers to add to each webhook call
          example:
            CustomEvent: this-is-a-test
        secretHeaders:
          type: object
          description: A map of headers with secret values, which will not be visible after saving
          example:
            Authorization: Basic user:password
        events:
          type: array
          description: List of events to subscribe to
          items:
            type: string
            enum:
            - order_status_update
            - template_preview_rendered
            - coupon_code_used
            - qr_code_scanned
            - mailing_sent
        filters:
          description: Applied filters
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/SingularV3WebhookFilter'
            - $ref: '#/components/schemas/PluralV3WebhookFilter'
      required:
      - name
      - url
      - active
      - events
    GetV3WebhookLogsResponseDto:
      type: object
      properties:
        id:
          type: string
          description: The id of the webhook log
        status:
          type: string
          enum:
          - success
          - failed
          description: The status of the webhook call
          example: success
        event:
          type: string
          description: The event of the triggered webhook log
          enum:
          - order_status_update
          - template_preview_rendered
          - coupon_code_used
          - qr_code_scanned
          - mailing_sent
        request:
          type: object
          description: The payload of the request
          example:
            id: ord_123
            status: order_created
          additionalProperties: true
        response:
          type: object
          description: The response of the called url
          example:
            status: 201
            body:
              message: OK!
          properties:
            status:
              type: number
              description: The status code of the response
              example: 200
            body:
              type: object
              description: The body of the response
              example:
                message: OK!
              additionalProperties: true
        createdAt:
          format: date-time
          type: string
          description: The timestamp at which the webhook was triggered
          example: '2024-01-01T00:00:00Z'
      required:
      - id
      - status
      - event
      - request
      - response
      - createdAt
    PaginatedDocumented:
      type: object
      properties:
        data:
          required: []
          title: Array of items
          properties: {}
          type: array
          items:
            type: object
        meta:
          title: Pagination Metadata
          allOf:
          - $ref: '#/components/schemas/PaginatedMetaDocumented'
        links:
          title: Links to pages
          allOf:
          - $ref: '#/components/schemas/PaginatedLinksDocumented'
      required:
      - meta
      - links
    SingularV3WebhookFilter:
      type: object
      properties:
        key:
          type: string
          description: The key to compare against
          example: status
        event:
          type: string
          description: The event the filter should apply on
          example: order_status_update
          enum:
          - order_status_update
          - template_preview_rendered
          - coupon_code_used
          - qr_code_scanned
          - mailing_sent
        type:
          type: string
          enum:
          - equals
          - not-equals
          example: equals
        value:
          type: string
          description: The value to compare against
          example: order_created
      required:
      - key
      - event
      - type
      - value
  securitySchemes:
    API_Key:
      type: apiKey
      in: header
      name: x-api-key
    Oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.print.one/v2/oauth/authorize
          refreshUrl: https://api.print.one/v2/oauth/token
          scopes:
            coupons.read: coupons.read
            coupons.write: coupons.write
            shorten.urls.read: shorten.urls.read
            shorten.urls.write: shorten.urls.write
            campaign.read: campaign.read
            campaign.write: campaign.write
            campaign.delete: campaign.delete
            company.read: company.read
            customfile.read: customfile.read
            customfile.write: customfile.write
            live.orders.read: live.orders.read
            live.orders.write: live.orders.write
            test.orders.read: test.orders.read
            test.orders.write: test.orders.write
            draft.orders.read: draft.orders.read
            draft.orders.write: draft.orders.write
            template.read: template.read
            template.write: template.write
            webhooks.read: webhooks.read
            webhooks.write: webhooks.write
            integrations.read: integrations.read
            tracking.event.read: tracking.event.read
            tracking.event.write: tracking.event.write
            live.batches.read: live.batches.read
            live.batches.write: live.batches.write
            test.batches.read: test.batches.read
            test.batches.write: test.batches.write
            tenant.admin: tenant.admin
            live.api.key: live.api.key
            test.api.key: test.api.key
          tokenUrl: https://api.print.one/v2/oauth/token
      name: Oauth2 Bearer Token