Colorado Timberline APIA Practical Guide to Successful Integration

Notifications

Overview

Notifications are synonymous with the concept of callbacks, and are labeled as such in the CT client libraries. In order to receive notifications from CT, you will have to expose an HTTP endpoint on your site where CT can send the notification requests. Currently there is only 1 notification type CT supports and that is an ‘Order Shipped’ notification. The contents include shipping and tracking information (if tracking info is supplied with the shipping type); see the protocol section of the site for more detailed information on notification payloads.

CT Client Library Approach

Depending on your binding approach, you may need to know some low-level details about how the protocol works in order to setup an endpoint for communication. If you’re implementing at the protocol level, you must know everything. Implementing at the library level gives you a couple of options. You will be implementing hook methods inside of notification callback classes. Here you can either bootstrap your library and leverage the default service endpoint, or you can embed the callback objects inside of your platform, bootstrapping the CT client library and passing in the contents notification request. Either way, with the client libraries, the main concept is that you will get back hydrated OPM objects, which abstract the protocol details from you.

No Status Polling

Order state can be inferred based upon notifications which have or have not been received. This means there is no reason for CT to expose an order status call. Calls of this nature tend to see frequent invocation from clients, which CT would have to sustain. We prefer the realtime nature of notifications.

If you are worried about missing a notification, we have a retry scheme in place so missing a notification should be rare if your systems have a decent uptime.

A notification attempt which does not result in a 200 HTTP response code (from your server) is considered a failure.  Notifications are retried up to 8 times, at an interval that:

  • starts at 5 minutes
  • doubles each failure

This means that notifications will be retried (less and less frequently) over the course of 10.5 hours. The following is an example of complete failure to notify your system:

  • attempt 1: 13:00
  • attempt 2: 13:05 (5 minutes after 1st attempt)
  • attempt 3: 13:15 (10 minutes after 2nd attempt)
  • attempt 4: 13:35 (20 minutes after 3rd attempt)
  • attempt 5: 14:15 (40 minutes later)
  • attempt 6: 15:35 (80 minutes later)
  • attempt 7: 18:15 (160 minutes later)
  • attempt 8: 23:35 (320 minutes later)

Please contact us after recovering from prolonged downtime of your notification receipt end point. We will reset failed notifications to you – restarting the retry cycle described above for each pending notification to you.