print-one Webhook Events API

openapi: 3.2.0
info:
  title: Print.one Webhook Events 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: Webhook Events
  v3:
    x-premiumAccess: true
  description: 'You can find more information about webhooks in our help center.


    Below you can find a list of supported webhook events:


    order_status_update


    template_preview_rendered


    coupon_code_used


    qr_code_scanned


    mailing_sent'
  x-premiumAccess: true
paths: {}
webhooks:
  order_status_update:
    post:
      tags:
      - Webhook Events
      parameters:
      - in: header
        name: X-Webhook-Event
        description: The event which triggered the webhook
        schema:
          type: string
          example: order_status_update
      - in: header
        name: X-Webhook-HMAC-SHA256
        description: Encrypted body with your webhook-secret - to verify the webhook request
        schema:
          type: string
      operationId: order_status_update
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/AddCampaignItemResponseDto'
                  description: The data sent with the webhook
                event:
                  type: string
                  description: The event which triggered the webhook
                  example: order_status_update
                created_at:
                  type: string
                  description: The date at which the webhook was triggered
                  example: '2024-01-01T12:00:00.000Z'
      responses:
        '200':
          description: Return a 20x status to indicate that the webhook was received successfully
        '400':
          description: Return a 40x status to indicate that the webhook could not be processed
        '500':
          description: Return a 50x status to indicate that the webhook could not be processed
      summary: Order status update
      x-summary-source: derived
  template_preview_rendered:
    post:
      tags:
      - Webhook Events
      parameters:
      - in: header
        name: X-Webhook-Event
        description: The event which triggered the webhook
        schema:
          type: string
          example: template_preview_rendered
      - in: header
        name: X-Webhook-HMAC-SHA256
        description: Encrypted body with your webhook-secret - to verify the webhook request
        schema:
          type: string
      operationId: template_preview_rendered
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/GetPreviewDetailsDto'
                  description: The data sent with the webhook
                event:
                  type: string
                  description: The event which triggered the webhook
                  example: template_preview_rendered
                created_at:
                  type: string
                  description: The date at which the webhook was triggered
                  example: '2024-01-01T12:00:00.000Z'
      responses:
        '200':
          description: Return a 20x status to indicate that the webhook was received successfully
        '400':
          description: Return a 40x status to indicate that the webhook could not be processed
        '500':
          description: Return a 50x status to indicate that the webhook could not be processed
      summary: Template preview rendered
      x-summary-source: derived
  coupon_code_used:
    post:
      tags:
      - Webhook Events
      parameters:
      - in: header
        name: X-Webhook-Event
        description: The event which triggered the webhook
        schema:
          type: string
          example: coupon_code_used
      - in: header
        name: X-Webhook-HMAC-SHA256
        description: Encrypted body with your webhook-secret - to verify the webhook request
        schema:
          type: string
      operationId: coupon_code_used
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/GetV3CouponCodeResponseDto'
                  description: The data sent with the webhook
                event:
                  type: string
                  description: The event which triggered the webhook
                  example: coupon_code_used
                created_at:
                  type: string
                  description: The date at which the webhook was triggered
                  example: '2024-01-01T12:00:00.000Z'
      responses:
        '200':
          description: Return a 20x status to indicate that the webhook was received successfully
        '400':
          description: Return a 40x status to indicate that the webhook could not be processed
        '500':
          description: Return a 50x status to indicate that the webhook could not be processed
      summary: Coupon code used
      x-summary-source: derived
  qr_code_scanned:
    post:
      tags:
      - Webhook Events
      parameters:
      - in: header
        name: X-Webhook-Event
        description: The event which triggered the webhook
        schema:
          type: string
          example: qr_code_scanned
      - in: header
        name: X-Webhook-HMAC-SHA256
        description: Encrypted body with your webhook-secret - to verify the webhook request
        schema:
          type: string
      operationId: qr_code_scanned
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/AddCampaignItemResponseDto'
                  description: The data sent with the webhook
                event:
                  type: string
                  description: The event which triggered the webhook
                  example: qr_code_scanned
                created_at:
                  type: string
                  description: The date at which the webhook was triggered
                  example: '2024-01-01T12:00:00.000Z'
      responses:
        '200':
          description: Return a 20x status to indicate that the webhook was received successfully
        '400':
          description: Return a 40x status to indicate that the webhook could not be processed
        '500':
          description: Return a 50x status to indicate that the webhook could not be processed
      summary: Qr code scanned
      x-summary-source: derived
  mailing_sent:
    post:
      tags:
      - Webhook Events
      parameters:
      - in: header
        name: X-Webhook-Event
        description: The event which triggered the webhook
        schema:
          type: string
          example: mailing_sent
      - in: header
        name: X-Webhook-HMAC-SHA256
        description: Encrypted body with your webhook-secret - to verify the webhook request
        schema:
          type: string
      operationId: mailing_sent
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/MailingResponseDto'
                  description: The data sent with the webhook
                event:
                  type: string
                  description: The event which triggered the webhook
                  example: mailing_sent
                created_at:
                  type: string
                  description: The date at which the webhook was triggered
                  example: '2024-01-01T12:00:00.000Z'
      responses:
        '200':
          description: Return a 20x status to indicate that the webhook was received successfully
        '400':
          description: Return a 40x status to indicate that the webhook could not be processed
        '500':
          description: Return a 50x status to indicate that the webhook could not be processed
      summary: Mailing sent
      x-summary-source: derived
components:
  schemas:
    AddCampaignItemResponseDto:
      type: object
      properties:
        id:
          type: string
          example: ord_1234567890
          description: Unique ID for the order
        companyId:
          type: string
          example: '1234567890'
          description: Unique ID for the company
        templateId:
          type: string
          example: tmpl_1234567890
          description: Template ID for the order
        templateVersion:
          type: number
          example: 1
          description: Version number of the template used for the order
        finish:
          type: string
          enum:
          - GLOSSY
          - MATTE
          example: GLOSSY
          description: Finish of the order
        format:
          type: string
          enum:
          - POSTCARD_A5
          - POSTCARD_A6
          - POSTCARD_SQ15
          - POSTCARD_MAXI
          - POSTCARD_DIN_LONG
          - GREETINGCARD_SQ14
          - LETTER_A4
          - SELFMAILER_MAXI
          example: POSTCARD_SQ15
          description: Format of the order. Can be null in the instance of a failed order without a valid design
        doubleSided:
          type: boolean
          example: true
          description: Whether the order is double sided or not (only when the product supports double-sided)
        sender:
          type: object
          example:
            name: string
            address: string
            addressLine2: string
            postalCode: string
            city: string
            country: string
          properties:
            name:
              type: string
              example: string
              description: Name of the sender
            address:
              type: string
              example: string
              description: Address of the sender
            addressLine2:
              type: string
              example: string
              description: Address line 2 of the sender
            postalCode:
              type: string
              example: string
              description: Postal code of the sender
            city:
              type: string
              example: string
              description: City of the sender
            country:
              type: string
              example: string
              description: Country of the sender
          description: Address information of the sender
        recipient:
          type: object
          example:
            name: string
            address: string
            addressLine2: string
            postalCode: string
            city: string
            country: string
          properties:
            name:
              type: string
              example: string
              description: Name of the sender
            address:
              type: string
              example: string
              description: Address of the sender
            addressLine2:
              type: string
              example: string
              description: Address line 2 of the sender
            postalCode:
              type: string
              example: string
              description: Postal code of the sender
            city:
              type: string
              example: string
              description: City of the sender
            country:
              type: string
              example: string
              description: Country of the sender
          description: Address information of the recipient
        definitiveCountryId:
          type: string
          example: NL
          description: Country ID of the order
        region:
          type: string
          example: NETHERLANDS
          description: Region of the order
        deliverySpeed:
          type: string
          enum:
          - FAST
          - SLOW
          example: FAST
          description: Delivery speed of the order
        stampId:
          type: string
          example: stmp_1234567890
          description: ID of the postal stamp that was used for this order. This property is optionally returned and only available as early preview (please apply if you wish to use this function).
        billingId:
          type: string
          example: Campaign name
          description: Shows up on invoice
        status:
          type: string
          example: order_created
          description: Status of the order
        friendlyStatus:
          type: string
          example: Success
          description: Friendly status of the order
        warnings:
          example:
          - Warning message
          description: Warnings of the order
          type: array
          items:
            type: string
        metadata:
          type: object
          example:
            foo: bar
          description: Metadata set by Print.one
          additionalProperties: true
        sendDate:
          format: date-time
          type: string
          example: '2021-01-01T00:00:00.000Z'
          description: Date the order is scheduled to be sent
        createdAt:
          format: date-time
          type: string
          example: '2021-01-01T00:00:00.000Z'
          description: Date the order was created
        updatedAt:
          format: date-time
          type: string
          example: '2021-01-01T00:00:00.000Z'
          description: Date the order was last updated
        anonymizedAt:
          format: date-time
          type: string
          example: '2021-01-01T00:00:00.000Z'
          description: Timestamp of when the order was anonymized
          nullable: true
        campaignId:
          type: string
          example: string
          description: ID of the campaign this item belongs to
        errors:
          description: Errors of the item
          type: array
          items:
            $ref: '#/components/schemas/ErrorDto'
        draft:
          type: boolean
          example: true
          description: If the item is marked as draft
        destination:
          type: string
          enum:
          - NETHERLANDS
          - GERMANY
          - INTERNATIONAL
          example: string
          description: Destination of the item
        mergeVariables:
          type: object
          additionalProperties:
            oneOf:
            - type: string
            - type: number
            - type: boolean
          example:
            firstName: John
            lastName: Doe
          description: Optional personalization data (can be an empty object)
        importId:
          type: string
          nullable: true
          description: The ID of the linked import
        auditLogs:
          description: Audit logs for the item
          type: array
          items:
            $ref: '#/components/schemas/AuditLogDto'
      required:
      - id
      - companyId
      - templateId
      - templateVersion
      - finish
      - format
      - doubleSided
      - sender
      - recipient
      - definitiveCountryId
      - region
      - deliverySpeed
      - billingId
      - status
      - friendlyStatus
      - warnings
      - metadata
      - sendDate
      - createdAt
      - updatedAt
      - anonymizedAt
      - campaignId
      - errors
      - draft
      - destination
      - importId
      - auditLogs
    ErrorDto:
      type: object
      properties:
        code:
          type: number
          example: 10006
          description: Unique code identifying the error type, or -1 if it could not be recognized
        status:
          type: number
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          - 7
          - 8
          - 9
          - 10
          - 11
          - 12
          - 13
          - 14
          - 15
          - 16
          example: 5
          description: The gRPC status code of the error
        message:
          type: string
          example: Resource not found
          description: A human readable description of the error
        errors:
          description: Child errors, present on aggregate errors that group multiple underlying failures
          type: array
          items:
            $ref: '#/components/schemas/ErrorDto'
      required:
      - code
      - status
      - message
    MailingResponseDto:
      type: object
      properties:
        id:
          type: string
          example: mail_1234567890
          description: Unique ID for the mailing
        templateId:
          type: string
          example: tmpl_1234567890
          description: Template ID for the order
        finish:
          type: string
          enum:
          - GLOSSY
          - MATTE
          example: GLOSSY
          description: Finish of the order
        format:
          type: string
          enum:
          - POSTCARD_A5
          - POSTCARD_A6
          - POSTCARD_SQ15
          - POSTCARD_MAXI
          - POSTCARD_DIN_LONG
          - GREETINGCARD_SQ14
          - LETTER_A4
          - SELFMAILER_MAXI
          example: POSTCARD_A6
          description: Format of the Mailing.
        destination:
          type: string
          example: NETHERLANDS
          description: Destination of the mailing
          enum:
          - NETHERLANDS
          - GERMANY
          - INTERNATIONAL
        orderCount:
          type: number
          example: 6000
          description: The number of orders in the mailing
        costs:
          type: object
          description: Costs of the mailing
          additionalProperties: false
          properties:
            total:
              type: number
              example: 1000
              description: Total cost of the mailing
            subtotal:
              type: number
              example: 800
              description: Subtotal cost before tax
            tax:
              type: number
              example: 200
              description: Tax applied to the mailing
        deliveryType:
          type: string
          example: DRIP
          description: The type of delivery for the mailing
        status:
          type: string
          example: MAILING_PAID
          description: The status of the mailing
        isSampleMailing:
          type: boolean
          example: false
          description: Whether this is an sample mailing
        createdAt:
          format: date-time
          type: string
          example: '2026-10-31T02:04:12.876Z'
          description: The date and time when the mailing was created
        sendDate:
          format: date-time
          type: string
          example: '2026-10-31T02:04:12.893Z'
          description: The date and time when the mailing was send
        qrScanCount:
          type: number
          example: 12
          description: Number of items in the mailing whose QR code was scanned
      required:
      - id
      - templateId
      - finish
      - format
      - destination
      - orderCount
      - costs
      - deliveryType
      - status
      - isSampleMailing
      - createdAt
      - sendDate
    GetPreviewDetailsDto:
      type: object
      properties:
        id:
          type: string
          description: The ID of the preview
          example: prev_zUsy4RK6bXSGrn3eqPDku-1
        templateId:
          type: string
          description: The ID of the template the preview was generated for
          example: tmpl_zUsy4RK6bXSGrn3eqPDku
        imageUrl:
          type: string
          description: The url of where to download the preview
          example: https://api.print.one/v2/storage/preview/prev_x0Pz2ljSkfRiJdsuxlZ46-1/details
        errors:
          description: List of errors that occurred during rending the preview
          example:
          - The resource at "https://example.com/idontexist.png" returned status code 404.
          type: array
          items:
            type: string
      required:
      - id
      - templateId
      - imageUrl
      - errors
    AuditLogDto:
      type: object
      properties:
        log:
          type: object
          example:
            status: order_created
          description: The audit log data
        createdAt:
          format: date-time
          type: string
          example: '2025-01-01T00:00:00.000Z'
          description: The timestamp of the audit log
      required:
      - log
      - createdAt
    GetV3CouponCodeResponseDto:
      type: object
      properties:
        id:
          type: string
          example: '1234567890'
          description: Unique ID for the Coupon Code
        couponId:
          type: string
          example: '1234567890'
          description: Unique ID for the Coupon
        code:
          type: string
          example: '1234567890'
          description: Code of the Coupon
        used:
          type: boolean
          example: false
          description: If the Coupon Code has been used
        usedAt:
          type: object
          description: Date when the Coupon Code was used
          example: '2024-01-01T00:00:00.000Z'
          nullable: true
        redeemedAt:
          type: object
          description: Date when the Coupon Code was redeemed
          example: '2024-01-01T00:00:00.000Z'
          nullable: true
        orderId:
          type: string
          example: ord_1234567890
          description: Order ID where the Coupon Code was used
          nullable: true
        createdAt:
          format: date-time
          type: string
          description: Date when the Coupon Code was created
          example: '2024-01-01T00:00:00.000Z'
        campaignId:
          type: string
          example: cmp_1234567890
          description: Campaign ID where the Coupon Code was used
          nullable: true
      required:
      - id
      - couponId
      - code
      - used
      - usedAt
      - redeemedAt
      - orderId
      - createdAt
      - campaignId
  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