CloudSignal Webhooks

This documentation describes the CloudSignal Webhooks v2.0

Table of content

• Getting started
• Basics
  • RESTful API
  • Request Data
  • Return Data
  • Retry
• Signals
  • CloudprinterOrderValidated
  • CloudprinterOrderCanceled
  • ItemValidated
  • ItemProduce
  • ItemProduced
  • ItemPacked
  • ItemShipped
  • ItemError
  • ItemCanceled
• Changes from v1.1 to 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

Your CloudSignal API endpoint must be RESTful. All calls must be implemented as HTTP post and with TLS encrypted. The HTTP response code 200 or 204 is expected on positive calls, all other response codes will be considered as error.

Request Data

All request data posted is as 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.

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

---

CloudprinterOrderCanceled

Confirmation that an order 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": "CloudprinterOrderCanceled",
    "order": "123456780000",
    "order_reference": "654321",
    "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: "CloudprinterOrderCanceled"	required
order	string	the full order id	required
order_reference	string	the clients order reference id	required
cause	string	cause id	required
message	string	reason for cancellation	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