CloudSignal Webhooks

This documentation describes the CloudSignal Webhooks v2.0

---

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 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 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 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 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 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 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 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 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.