Best Practice

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 transaction.status

All of the notifications that we send always have transaction.status parameter. The possible value is SUCCESS or 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 transaction.status FAILED.

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.

Sample Code

Here are the sample code on how you can handle the notification in various programming languages:

Coming soon
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.