Available from 3.1.0 4ws.trade release
Overview#
This documentation provides detailed instructions for implementing an external system that receives JSON data via a webhook whenever a sale is closed in the Mobile Shop system, particularly when a promotion has been applied to the customer's purchase. The system also includes error handling to save the JSON payload in case of processing errors and notify the IT department for further investigation.Functionality Description#
Trigger Condition#
The external system will receive a webhook notification when a sale is closed in the Mobile Shop system, specifically when a promotion has been applied to the customer's purchase.Webhook Notification#
The notification is sent as a JSON payload to a predefined URL. The payload contains details about the customer and any changes to their data due to the promotion.Example JSON Payload Structure#
The webhook notification is sent as a JSON payload with the following structure:{
"subjectCode": "1026311",
"cardBarcode": "9990000100880",
"data": {
"83394a21-e3c0-489d-8a10-7f08041b21aa": {
"YEAR_2024": {
"purchaseThreshold": 832.71,
"voucherAmount": 0
}
}
},
"attributesChanged": [
"83394a21-e3c0-489d-8a10-7f08041b21aa"
]
}
JSON Fields Description#
subjectCode: The unique identifier for the customer.
cardBarcode: The barcode of the customer's loyalty card.
data: An object containing the promotional data.The keys within the data object represent unique UUIDs for each promotion.
Each promotion contains nested objects, typically structured by year, with specific attributes.purchaseThreshold: The total amount of purchases made by the customer.
voucherAmount: The amount of vouchers available for the customer to use.
attributesChanged: An array of UUIDs indicating which promotions have had attribute changes.
Implementation Steps#
1. Webhook Endpoint Setup#
Create an endpoint in the external system to receive POST requests. This endpoint will handle the incoming JSON payloads.Example in Node.js/Express#
2. Processing the Data#
Implement the logic to process the received promotion data. This can include updating customer records, applying discounts, or triggering other business processes.3. Error Handling#
Implement error handling to manage possible issues during data processing, such as logging errors, saving the JSON payload, and sending notifications to the IT department.Example Error Handling#
The error handling mechanism saves the JSON payload to a file and sends a notification to the IT department.4. Notification Mechanism#
The system should include a mechanism to notify the IT department in case of errors. This can be implemented using email, SMS, or any other suitable communication method.Sequence Diagram#
Examples#
Example JSON Notification#
The following example JSON payload represents a customer whose total purchase threshold has been updated and who has no vouchers available:{
"subjectCode": "1026311",
"cardBarcode": "9990000100880",
"data": {
"83394a21-e3c0-489d-8a10-7f08041b21aa": {
"YEAR_2024": {
"purchaseThreshold": 832.71,
"voucherAmount": 0
}
}
},
"attributesChanged": [
"83394a21-e3c0-489d-8a10-7f08041b21aa"
]
}
Example Webhook Handling Code#
The following Node.js code example shows how to set up a webhook endpoint to receive and process the JSON payload, including error handling, saving failed payloads, and notifying the IT department:Conclusion#
This documentation provides the necessary details to implement an external system that receives and processes webhook notifications from the Mobile Shop system upon the closure of a sale with applied promotions. The system includes robust error handling to save failed payloads and notify the IT department for further investigation. By following the outlined steps and examples, the integration can be implemented effectively.