Spreadshirt Subscriptions API
This api offers you webhook subscriptions that will notify you about changes with your order via a POST request. ### Acknowledge notifications Notifications are following the at *least once principal* and therefore are guaranteed to be delivered at least once. Part of this principal is also that notifications needs to be acknowledged with * a status code of 202 * a response within 8 seconds * the payload `[accepted]` If any of the above criteria does not match, the notification is handled as not received and will be sent again at a later stage. The retry mechanism will increase the delay over time to not flood your system. ### Validate authenticity of notifications Webhook will make notifications with the `X-SPRD-SIGNATURE` header if a subscription was setup with a secret. Consumers can protect against counterfeit requests by comparing the provided signature with what they've calculated on their side. The signature is a `SHA256 HMAC` over the request body and is encoded in `Base64`. # Events If you register a subscription, you will get the following events, in case there is a state change. ## Article.added Event If a new article is added to a point of sale, you will get the following notification. If you want to check how the article object looks like go to the link: [getArticle](#operation/getArticle) ``` { "eventType": "Article.added", "data": { "pointOfSaleId": "123", "article": "...object" } } ``` ## Article.updated Event If a existing article is updated, you will get the following notification. If you want to check how the article object looks like go to the link: [getArticle](#operation/getArticle) ``` { "eventType": "Article.updated", "data": { "pointOfSaleId": "123", "article": "...object" } } ``` ## Article.removed Event If a article is removed from a point of sale, you will get the following notification. If you want to check how the article object looks like go to the link: [getArticle](#operation/getArticle) ``` { "eventType": "Article.removed", "data": { "pointOfSaleId": "123", "article": "...object" } } ``` ## Order.cancelled Event If your order is cancelled, you will get the following notification. If you want to check how the order object looks like go to the link: [getOrder](#operation/getOrder) ``` { "eventType": "Order.cancelled", "data": { "pointOfSaleId": "123", "order": "...object" } } ``` ## Order.processed Event If your order is completely processed, you will get the following notification. If you want to check how the order object looks like go to the link: [getOrder](#operation/getOrder) ``` { "eventType": "Order.processed" "data": { "pointOfSaleId": "123", "order": "...object" } } ``` ## Order.needs-action Event If an error occurs in your order, you will get the following notification. If you want to check how the order object looks like go to the link: [getOrder](#operation/getOrder) ``` { "eventType": "Order.needs-action" "data": { "pointOfSaleId": "123", "errorReason": "string" "order": "...object" } } ``` ## Shipment.sent Event If a part of your order is shipped, you will get the following notification. If you want to check how the order object looks like go to the link: [getShipments](#operation/getShipments) ``` { "eventType": "Shipment.sent", "data": { "pointOfSaleId": "123", "shipment": "...object" } } ``` # Simulate Events Simulate order events by sending us a POST request. You can use this feature for development to trigger some of the available events, without modifying the orders. It is available only for our staging environment. ### How do I use simulated Events? To use this feature you need to create an extra account on https://app.spreadconnect-staging.app and get a **Spreadconnect API Key** for this account. See step 2 and 3 in the **Authentication** section. To send requests to the Spreadconnect API on staging you need use https://rest.spreadconnect-staging.app as the base url. Also you will need to use the Spreadconnect API key from your staging account in the header of your request to authenticate it. ### What is staging? Staging is a test environment separate from the live environment. The data in the staging environment is for testing purposes only. Adding, manipulating or deleting articles and orders in the staging environment does not have any real world effects. An order that is put into production in the staging environment will not actually get produced and shipped. Also note that part of the content of the payload you get from simulated events is mocked and does not reflect the exact data which would be send if the real events would be triggered automatically.