CloudSignal Webhooks

This documentation describes the CloudSignal Webhooks v2.1

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.

The configuration also available in the client dashboard - all parameters can be changed using clear interface.

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

json

{
    "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

json

{
    "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

json

{
    "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

json

{
    "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

json

{
    "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

json

{
    "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",
  	"url": "https://gls-group.eu/EU/en/parcel-tracking?match=1A2B3C4D5E6F"
}

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
url	string	Absolute HTTPS tracking URL, URI syntax RFC 3986	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

json

{
    "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

json

{
    "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

ItemDeliveryStarted

Confirmation that an item has been passed to delivery office.

Example request

json

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemDeliveryStarted",
    "order": "123456780000",
    "item": "123456780001",
    "order_reference": "654321",
    "item_reference": "321",
  	"tracking": "1A2B3C4D5E6F",
    "message": "	Arrived Shipping Partner Facility",
    "datetime": "2017-01-21T13:23:42+00:00"
}

Parameters

Name	Type	Description	Required
apikey	string	api access key	required
type	string	valid value: "ItemDeliveryStarted"	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 number	optional
message	string	shipping tracking details	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

ItemDeliveryCompleted

Confirmation that an item has been successfully delivered.

Example request

json

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemDeliveryCompleted",
    "order": "123456780000",
    "item": "123456780001",
    "order_reference": "654321",
    "item_reference": "321",
  	"tracking": "1A2B3C4D5E6F",
    "message": "Available for Pickup",
    "datetime": "2017-01-21T13:23:42+00:00"
}

Parameters

Name	Type	Description	Required
apikey	string	api access key	required
type	string	valid value: "ItemDeliveryCompleted"	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 number	optional
message	string	shipping tracking details	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

ItemDeliveryFailed

Signal for unsuccessfull delivery (return or lost).

Example request

json

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemDeliveryFailed",
    "order": "123456780000",
    "item": "123456780001",
    "order_reference": "654321",
    "item_reference": "321",
  	"tracking": "1A2B3C4D5E6F",
    "message": "Package returned back",
    "datetime": "2017-01-21T13:23:42+00:00"
}

Parameters

Name	Type	Description	Required
apikey	string	api access key	required
type	string	valid value: "ItemDeliveryFailed"	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 number	optional
message	string	shipping tracking details	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 v2.0 to v2.1

The following list describes the changes made from version 2.0 and 2.1 of the CloudSignal Webhooks.

Added 3 new item signal types (delivery):

ItemDeliveryStarted - item passed to delivery office.
ItemDeliveryCompleted - item successfully delivered.
ItemDeliveryFailed - unsuccessfull delivery.

CloudSignal Webhooks ​

Getting started ​

Basics ​

RESTful API ​

Request Data ​

Return Data ​

Your RESTful API endpoint ​

Retry ​

Signals ​

CloudprinterOrderValidated ​

ItemValidated ​

ItemProduce ​

ItemProduced ​

ItemPacked ​

ItemShipped ​

ItemError ​

ItemCanceled ​

ItemDeliveryStarted ​

ItemDeliveryCompleted ​

ItemDeliveryFailed ​

Changes from v2.0 to v2.1 ​

CloudSignal Webhooks

Getting started

Basics

RESTful API

Request Data

Return Data

Your RESTful API endpoint

Retry

Signals

CloudprinterOrderValidated

ItemValidated

ItemProduce

ItemProduced

ItemPacked

ItemShipped

ItemError

ItemCanceled

ItemDeliveryStarted

ItemDeliveryCompleted

ItemDeliveryFailed

Changes from v2.0 to v2.1