Manufacturer Webhook - XMPieLab/uStore-NG GitHub Wiki
Manufacturer Webhook
uStore provides the default manufacturer allocation option, by which the manufacturer is set on the product level, so all order items of the same product are assigned to the same manufacturer. If you wish to set a specific manufacturer for each item in the shopping cart, you can use an external service (manufacturer webhook). The webhook gets the order data and returns the manufacturer per order item.
Read more:
Adding a manufacturer webhook in uStore
Manufacturer webhook sample application
Manufacturer webhook sample application documentation
The following activity diagram shows uStore's communication with the manufacturer webhook.
HTTP request to the webhook
uStore sends data to the webhook from the stored procedure in JSON format, in the body of the HTTP POST request.
The request should have the following headers:
- Content-Type: application/json
- X-Signature: hashing of the request body (the body needs to be hashed with the signatureKey using SHA-512 algorithm)
Optional headers:
- Accept-Language: culture code of current culture, i.e. en-US or fr-FR.
Example of a request body
{
"Order":{
"@OrderId":"5295",
"@DisplayOrderId":"85925",
"@cartCreationdDate":"2023-03-27T02:13:55.410",
"@primaryCurrency":"USD",
"Prices":{
"Subtotal":"5.00000",
"ShippingPrice":"0.00000",
"MailingPrice":"0.00000",
"Tax":"0.00000",
"CouponDiscount":{
"@CouponID":"0",
"#text":"0.00000"
},
"TotalPrice":"3.00000",
"Cost":"0.00000"
},
"Store":{
"@Id":"8",
"@externalId":"[email protected]",
"@LandingDomain":"",
"Currency":"USD",
"PickupAddress":{
"Name":"ups1",
"Company":"ups1",
"Address1":"208E 31 st.",
"Address2":null,
"City":"New York",
"State":"NY",
"ZipCode":"10016",
"Country":"US",
"Phone":"9172653927",
"Fax":null,
"AddressReference":null
}
},
"User":{
"@UserId":"1",
"@externalId":"[email protected]",
"FirstName":"uStore2",
"LastName":"Superuser",
"Email":"[email protected]",
"Phone":null,
"Mobile":null,
"Fax":null,
"Company":null,
"Department":null,
"JobTitle":null
},
"Deliveries":null,
"OrderProducts":{
"OrderProduct":[
{
"@id":"3087",
"@creationDate":"2023-03-29T10:57:24.680",
"@OutputToken":"68785D20-8710-48CF-9DCE-FED95CD27430",
"Quantities":{
"NumberOfRecipients":"1",
"NumberOfCopies":"1",
"TotalUnits":"1"
},
"Prices":{
"FixedPrice":"0.00000",
"PricePerRecipient":"1.00000",
"PricePerUnit":"1.00000",
"Subtotal":"1.00000",
"MailingPrice":"0.00000",
"TotalPrice":"1.00000",
"Cost":"0.00000"
},
"Manufacturer":{
"@externalId":"",
"Name":"test2 Manufacturer",
"Address":{
"Name":"439 Columbia Boulevard",
"Company":null,
"Address1":"439 Columbia Boulevard",
"Address2":null,
"City":"Hanover",
"State":"MD",
"ZipCode":"21076",
"Country":"US",
"Phone":"410-428-7084",
"Fax":null,
"AddressReference":null
}
},
"Deliveries":null,
"ProductUnit":{
"@id":"1",
"@itemsAmount":"1",
"#text":"Item"
},
"Product":{
"@id":"240",
"@externalId":"",
"Name":"copy[10]s1",
"CatalogNumber":null,
"Type":"StaticPrint",
"Downloadable":"false",
"Manufacturer":{
"@externalId":"",
"Name":"test2 Manufacturer",
"Address":{
"Name":"439 Columbia Boulevard",
"Company":null,
"Address1":"439 Columbia Boulevard",
"Address2":null,
"City":"Hanover",
"State":"MD",
"ZipCode":"21076",
"Country":"US",
"Phone":"410-428-7084",
"Fax":null,
"AddressReference":null
}
},
"TaxGroup":{
"Id":"1",
"Name":"Regular Tax",
"TaxCode":null
}
},
"DialValues":null,
"PropertyValues":{
"PropertyValue":[
{
"Property":{
"@id":"11441",
"@externalId":"",
"DisplayName":"Base"
},
"Value":""
},
{
"Property":{
"@id":"11442",
"@externalId":"",
"DisplayName":"prop2"
},
"Value":"uStore2"
}
]
}
},
{
"@id":"3088",
"@creationDate":"2023-04-12T01:36:39.520",
"@OutputToken":"CEA9F245-E023-45FE-B68D-9A0A3CAB3DA3",
"Quantities":{
"NumberOfRecipients":"1",
"NumberOfCopies":"1",
"TotalUnits":"1"
},
"Prices":{
"FixedPrice":"1.00000",
"PricePerRecipient":"1.00000",
"PricePerUnit":"1.00000",
"Subtotal":"2.00000",
"MailingPrice":"0.00000",
"TotalPrice":"2.00000",
"Cost":"0.00000"
},
"Manufacturer":{
"@externalId":"",
"Name":"test2 Manufacturer",
"Address":{
"Name":"439 Columbia Boulevard",
"Company":null,
"Address1":"439 Columbia Boulevard",
"Address2":null,
"City":"Hanover",
"State":"MD",
"ZipCode":"21076",
"Country":"US",
"Phone":"410-428-7084",
"Fax":null,
"AddressReference":null
}
},
"Deliveries":null,
"ProductUnit":{
"@id":"1",
"@itemsAmount":"1",
"#text":"Item"
},
"Product":{
"@id":"73",
"@externalId":"",
"Name":"static1",
"CatalogNumber":null,
"Type":"StaticPrint",
"Downloadable":"false",
"Manufacturer":{
"@externalId":"",
"Name":"test2 Manufacturer",
"Address":{
"Name":"439 Columbia Boulevard",
"Company":null,
"Address1":"439 Columbia Boulevard",
"Address2":null,
"City":"Hanover",
"State":"MD",
"ZipCode":"21076",
"Country":"US",
"Phone":"410-428-7084",
"Fax":null,
"AddressReference":null
}
},
"TaxGroup":{
"Id":"1",
"Name":"Regular Tax",
"TaxCode":null
}
},
"DialValues":null,
"PropertyValues":{
"PropertyValue":[
{
"Property":{
"@id":"11253",
"@externalId":"",
"DisplayName":"Base"
},
"Value":""
}
]
}
}
]
},
"CustomConfiguration":"1:2;2:1;3:3",
"DeliveryInformation":{
"Deliveries":[
{
"ShippingAddress":{
"Address1":"4616 Wines Lane",
"Address2":null,
"Company":"4616 Wines Lane",
"Name":"Wines Lane",
"CountryName":"United States",
"Fax":null,
"Phone":"832-293-2670",
"Zip":"19028",
"StateName":"Pennsylvania"
},
"DeliveryItems":[
{
"OrderProductID":"3087",
"NumberOfUnits":"1"
}
],
"DeliveryMethod":"Shipping"
},
{
"ShippingAddress":{
"Address1":"4616 Wines Lane",
"Address2":null,
"Company":"4616 Wines Lane",
"Name":"Wines Lane",
"CountryName":"United States",
"Fax":null,
"Phone":"832-293-2670",
"Zip":"19028",
"StateName":"Pennsylvania"
},
"DeliveryItems":[
{
"OrderProductID":"3088",
"NumberOfUnits":"1"
}
],
"DeliveryMethod":"Shipping"
}
]
}
}
}
HTTP response from the webhook
The webhook returns data with the manufacturer per order item in JSON format.
The response should have the following headers:
- Content-Type: application/json
- X-Signature: hashing of the response body (the body needs to be hashed with the signatureKey using SHA-512 algorithm)
Example of a response body
{
"3087":"2",
"3088":"1"
}
This example shows that the manufacturer which is assigned id=2 is responsible for order item id=3087, and the manufacturer which is assigned id=1 is responsible for order item id=3088.
Error handling
Error messages can be propagated from the webhook back to uStore.
You should return in the response a status code 400 (BadRequest) and pass the error message in the body as follows:
{
"message": "...error message text..."
}
The language of the error message may depend on the culture code from the Accept-Language header of the webhook HTTP request.
Hashing the body
uStore hashes the body of the request and sends it in the X-Signature header, and expects the webhook to do the same for the body of the response.
The hashing is done with the signatureKey using SHA-512 algorithm.