CloudSignal Webhooks

This documentation describes the CloudSignal Webhooks v2.0

Table of content

Getting started


To get started with Cloudprinter please contact us at info@cloudprinter.com to get your account created. To each account is associated an API key, which is used as authentication in all API calls. Each webhook request includes a Webhook API key, which is different from the account API key. This Webhook API key sould be validated on each request.

Basics


RESTful API

The CloudSignal Webhooks is RESTful. All calls are implemented as HTTP post and TLS encrypted. The HTTP response code 200 is expected on positive calls, all other response codes is considered as error.

Request Data

All request data posted is in JSON objects. The documentation for each webhook describes the request data parameters in detail.

Return Data

No return data is expected and will be ignored.

Your RESTful API endpoint

Each client can have one RESTful API endpoint for use with CloudSignal Webhooks. The endpoint URL is configured by Cloudprinter.

Retry

CloudSignal Webhooks will retry sending signals if HTTP status 200 or 204 is not returned. Max 100 attempts over 7 days.

Signals


CloudprinterOrderValidated

Order received and validated by Cloudprinter.

Example JSON request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "CloudprinterOrderValidated",
    "order": "123456780000",
    "order_reference": "654321",
    "datetime": "2017-01-21T13:23:42+00:00"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: "CloudprinterOrderValidated" required
order string the full order id required
order_reference string the clients order reference id required
datetime string ISO 8601 timestamp required

HTTP Status codes

Code Status Description
200 OK the request has succeeded
204 No content the request has succeeded, order not found
400 Bad request the request was invalid or parameters are missing. Causes signal delivery retry

ItemValidated

Item received and validated by the production.

Example JSON request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemValidated",
    "order": "123456780000",
    "item": "123456780001",
    "order_reference":"654321",
    "item_reference":"321",
    "datetime": "2017-01-21T13:23:42+00:00"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: "ItemValidated" required
order string the full order id required
item string the full item id required
order_reference string the clients order reference id required
item_reference string the clients item reference id required
datetime string ISO 8601 timestamp, production signal timestamp required

HTTP Status codes

Code Status Description
200 OK the request has succeeded
204 No content the request has succeeded, order not found
400 Bad request the request was invalid or parameters are missing. Causes signal delivery retry

ItemProduce

Production has started for item.

Example JSON request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemProduce",
    "order": "123456780000",
    "item": "123456780001",
    "order_reference":"654321",
    "item_reference":"321",
    "datetime": "2017-01-21T13:23:42+00:00"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: "ItemProduce" required
order string the full order id required
item string the full item id required
order_reference string the clients order reference id required
item_reference string the clients item reference id required
datetime string ISO 8601 timestamp, production signal timestamp required

HTTP Status codes

Code Status Description
200 OK the request has succeeded
204 No content the request has succeeded, order not found
400 Bad request the request was invalid or parameters are missing. Causes signal delivery retry

ItemProduced

Production completed for item.

Example JSON request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemProduced",
    "order": "123456780000",
    "item": "123456780001",
    "order_reference":"654321",
    "item_reference":"321",
    "datetime": "2017-01-21T13:23:42+00:00"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: "ItemProduced" required
order string the full order id required
item string the full item id required
order_reference string the clients order reference id required
item_reference string the clients item reference id required
datetime string ISO 8601 timestamp, production signal timestamp required

HTTP Status codes

Code Status Description
200 OK the request has succeeded
204 No content the request has succeeded, order not found
400 Bad request the request was invalid or parameters are missing. Causes signal delivery retry

ItemPacked

Item has been packed.

Example JSON request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemPacked",
    "order": "123456780000",
    "item": "123456780001",
    "order_reference":"654321",
    "item_reference":"321",
    "datetime": "2017-01-21T13:23:42+00:00"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: "ItemPacked" required
order string the full order id required
item string the full item id required
order_reference string the clients order reference id required
item_reference string the clients item reference id required
datetime string ISO 8601 timestamp, production signal timestamp required

HTTP Status codes

Code Status Description
200 OK the request has succeeded
204 No content the request has succeeded, order not found
400 Bad request the request was invalid or parameters are missing. Causes signal delivery retry

ItemShipped

Item has been shipped. The tracking code for the packet is included in this signal.

Example JSON request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemShipped",
    "order": "123456780000",
    "item": "123456780001",
    "order_reference":"654321",
    "item_reference":"321",
    "tracking": "1A2B3C4D5E6F",
    "shipping_option": "GLS",
    "datetime": "2017-01-21T13:23:42+00:00"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: "ItemShipped" required
order string the full order id required
item string the full item id required
order_reference string the clients order reference id required
item_reference string the clients item reference id required
tracking string tracking code for the item required
shipping_option string shipping option required
datetime string ISO 8601 timestamp, production signal timestamp required

HTTP Status codes

Code Status Description
200 OK the request has succeeded
204 No content the request has succeeded, order not found
400 Bad request the request was invalid or parameters are missing. Causes signal delivery retry

ItemError

Item has problem or error. This could be due print error or failed in quality check etc.

Example JSON request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemError",
    "order": "123456780000",
    "item": "123456780001",
    "order_reference":"654321",
    "item_reference":"321",
    "cause": "Print error, reprint needed",
    "delay": "24",
    "datetime": "2017-01-21T13:23:42+00:00"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: "ItemError" required
order string the full order id required
item string the full item id required
order_reference string the clients order reference id required
item_reference string the clients item reference id required
cause string text string explaning the error optional
delay string expected delay in hours optional
datetime string ISO 8601 timestamp, production signal timestamp required

HTTP Status codes

Code Status Description
200 OK the request has succeeded
204 No content the request has succeeded, order not found
400 Bad request the request was invalid or parameters are missing. Causes signal delivery retry

ItemCanceled

Confirmation that an item has been cancelled in production and in Cloudprinter. Cancel requests are normally based on a request by the client.

Example JSON request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemCanceled",
    "order": "123456780000",
    "item": "123456780001",
    "order_reference": "654321",
    "item_reference": "321",
    "cause": "190",
    "message": "Example message",
    "datetime": "2017-01-21T13:23:42+00:00"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: "ItemCanceled" required
order string the full order id required
item string the full item id required
order_reference string the clients order reference id required
item_reference string the clients item reference id required
cause string cause id optional
message string reason for cancellation optional
datetime string ISO 8601 timestamp, production signal timestamp required

HTTP Status codes

Code Status Description
200 OK the request has succeeded
204 No content the request has succeeded, order not found
400 Bad request the request was invalid or parameters are missing. Causes signal delivery retry

Changes from v1.1 to v2.0


The following list describes the changes made from version 1.1 and 2.0 of the CloudSignal Webhooks. When updating from 1.1 to 2.0 please go through these changes. The CloudSignal Webhooks v2.0 will not be active until activated in CloudAdmin.

  • the parameter order now contains full Cloudprinter order id.
  • the parameter item now contains the full Cloudprinter item id.
  • the parameter order_reference has been added to all JSON requests and contains the clients order reference id.
  • the parameter item_reference has been added to all JSON requets except CloudprinterOrderValidated and contains the clients item reference id.
  • the parameter shipping_option has been added to ItemShipped.
  • the parameter datetime has been updated to ISO 8691 format.