Order Approval Webhook
uStore provides out-of-the-box order approval methods, which are suitable for specific order approval use cases. When the required order approval cannot be fulfilled by the available methods, you can integrate an external service using the order approval webhook. The webhook gets the order data and returns the required approval group for the submitted order.
Read more:
Setting up an order approval process in uStore
Order approval sample application
Order approval webhook sample application documentation
The following activity diagram shows uStore's communication with the order approval 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).
Example of a request body
{
"Order":{
"@OrderId":"4068",
"@DisplayOrderId":"28604",
"@cartCreationdDate":"2022-11-22T12:47:36.197",
"@primaryCurrency":"USD",
"Prices":{
"Subtotal":"1.00000",
"ShippingPrice":"0.00000",
"MailingPrice":"0.00000",
"Tax":"0.20000",
"Taxes":{
"@RoundingAmount":"0.00",
"@Amount":"0.20",
"Tax":[
"@Name":"Regular Tax",
"@DisplayName":"Display_Regular Tax",
"@Percentage":"20.0",
"#text":"0.200000"
]
},
"CouponDiscount":{
"@CouponID":"0",
"#text":"0.00000"
},
"TotalPrice":"1.20000",
"Cost":"0.00000"
},
"Store":{
"@Id":"7",
"@externalId":"test@uStore.com",
"@LandingDomain":"",
"Currency":"USD",
"PickupAddress":null
},
"User":{
"@UserId":"1",
"@externalId":"",
"FirstName":"uStore",
"LastName":"Superuser",
"Email":"test@uStore.com",
"Phone":null,
"Mobile":null,
"Fax":null,
"Company":null,
"Department":null,
"JobTitle":null
},
"BillingAddress":{
"Name":"alex",
"Company":null,
"Address1":"test street 46",
"Address2":null,
"City":"dallas",
"State":"TX",
"ZipCode":"75001",
"Country":"US",
"Phone":"2148280976",
"Fax":null,
"AddressReference":"test street 46"
},
"Deliveries":{
"Delivery":[
"Method":"Void",
"DeliveryProvider":{
"@id":"6",
"#text":"Void Delivery"
},
"DeliveryService":{
"@id":"6",
"#text":"Void"
},
"DeliveryPrice":"0.00000",
"ShippingTax":{
"@Percentage":"0.00000",
"#text":"0.00000"
},
"ShippingAddress":null,
"DeliveryItems":{
"DeliveryItem":[
"@id":"156",
"OrderProductId":"127",
"NumberOfUnits":"1"
]
}
]
},
"OrderProducts":{
"OrderProduct":[
"@id":"127",
"@creationDate":"2022-11-23T11:56:25.927",
"@OutputToken":"3B537BKC-2B41-4B22-84F4-6296CE65E1FF",
"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",
"Tax":{
"@Percentage":"20.00000",
"#text":"0.20000"
}
},
"Deliveries":{
"Delivery":[
"Method":"Void",
"DeliveryProvider":{
"@id":"6",
"#text":"Void Delivery"
},
"DeliveryService":{
"@id":"6",
"#text":"Void"
}
]
},
"ProductUnit":{
"@id":"1",
"@itemsAmount":"1",
"#text":"Item"
},
"Product":{
"@id":"26",
"@externalId":"",
"Name":"s1",
"CatalogNumber":null,
"Type":"StaticPrint",
"Downloadable":"false",
"Manufacturer":{
"@externalId":""
},
"TaxGroup":{
"Id":"1",
"Name":"Regular Tax",
"TaxCode":null
}
},
"DialValues":null,
"PropertyValues":{
"PropertyValue":[
"Property":{
"@id":"10054",
"@externalId":"",
"DisplayName":"Base"
},
"Value":""
]
}
]
},
"Clearing":{
"@type":"Invoice",
"Value":{
"NoClearing":null
}
},
"CustomerNoteToApprover":"Please approve the order",
"CustomConfig":"true;10065"
}
}
The webhook returns data with ApprovalGroupId and IsApprovalNeeded flag 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)
Description of a response body
{
"ApprovalGroupId": number,
"IsApprovalNeeded": boolean
}
Example of a response body
{
"ApprovalGroupId": 10065,
"IsApprovalNeeded": true
}
Error messages can be propagated from the order approval service or 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..."
}
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.