Handling HTTP Notification is crucial in order to make sure that your integration's business logic works as expected. Here are some best practices that you need to implement:
Handling Notification Implementation
Acknowledge HTTP Notification immediately
If your HTTP Notification endpoint performs complex logic, or makes network calls, it's possible that the endpoint would time out before Jokul sees its complete execution. Ideally, your HTTP Notification handler code (acknowledging receipt of an event by returning a 2xx status code) is separate of any other logic you do for that notification.
Verify HTTP Notification authenticity
You must verify the HTTP Notification to make sure that it is coming from Jokul. To do that, you need to check the
Signature on the Request Header that sent to you. Learn more about generating Signature here.
Update the transaction status based on the
All of the notifications that we send always have
transaction.status parameter. The possible value is
FAILED. Update the transaction status on your side based on this value.
Jokul Checkout Implementation
Jokul Checkout User Experience is designed to increase your payment success rate, meaning that it allows your customers to change payment method if one is failed. Therefore, if you are integrating with Jokul Checkout, you must ignore the
Handle duplicate events
HTTP Notification endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already-logged events.
Parse HTTP Notification in non-strict format
Jokul sends the notification body as JSON, please parse the JSON with a JSON parser. Always expect new fields will be added to the notification body, so parse it in a non strict format. This prevents the parser from throwing an exception for new fields. It should gracefully ignore the new fields. This allows us to extend our notification system for newer use cases without breaking old clients.
Here are the sample code on how you can handle the notification in various programming languages:
Jokul Plugins handles the notification for you
If you are using Jokul Plugins, the notification is handled by the plugin itself. The order status on the CMS will update accordingly based on the notification received.