Push Notifications Architecture
NetLook encourages API consumers to utilize our Push Notification system to track real time data changes. The
Push Notifications are a server-to-server publish/subscribe protocol for Web-accessible resources. Notifications
are pushed out to subscribers via HTTP messages, which is much more efficient than polling-based solutions.
Partner servers find out about events in near real-time, without having to determine the optimal polling
interval or repeatedly fetching data that hasn’t changed.
In order to utilize the push notifications you will need to provide an HTTP listener end point that can receive
the notifications from the NVR-API. The NVR-API provides the Notification resource for you to connect to. These
are the operations that are dedicated to work with the Notification resource:
| Operation | Description |
|---|---|
| Delete Setup | Remove (DELETE) your endpoint from the NetLook system to disable all future notifications. |
| Get Setup | Retrieve (GET) details about your notification setup to ensure that the NVR-API is configured properly to send push notifications to your end point. |
| Get Subscriptions | Retrieve (GET) a list of all dealer topics which notifications are being sent for. |
| Setup | Define (POST) the endpoint URL for your HTTP listener to determine where notifications are delivered. |
| Subscribe Dealer | Define (POST) the dealer which notifications will be delivered for. |
| Unsubscribe Dealer | Define (DELETE) a dealer to remove from the set of dealers which notifications are being sent for. |
Notifications will have a subject to help define what type of information needs to be retrieved, updated or
removed to keep the systems in sync. The notification topics are “NewRecord”, “RecordChange”, “PriceChange”,
“PhotosChange”, “VideosChange”, “CommentsChange”, and “DeleteRecord”.
The notification message itself will contain a vehicle URL which can be read and visited to get vehicle
information (see “Get Vehicle” operation in the “Vehicle” resource section).
If you process NVR-API notifications in near real time, this will provide the most efficient and most real-time solution for the dealers which data is being exchanged about. Your application should respond to notifications with a standard HTTP status of 200 OK. Absent this response, NetLook will attempt redelivery of notifications, but after a number of failed delivery attempts, NetLook will stop resending.
Subscribing to Notifications
- 1. Submit a Notification Setup request to the NVR-API to define your listener end point.
- 2. Submit Subscribe Dealer requests to the NVR-API to activate notifications for dealer inventory.
That is all that is takes to get started with notifications.
Processing Notifications
Notifications will contain a subject and a body that will help you to determine what action to take when receiving a notification. Each notification body will contain a URL to perform a READ of the vehicle data. The subject will indicate what type of action you might want to program in response to the notification. Different subjects may require that you perform different actions. These are the subjects that are supported:
| Subject | Cause | Possible Partner Action |
|---|---|---|
| NewRecord | A dealer has inserted a new auto into inventory. | Add a new record with all data that is needed from NetLook. |
| PriceChange | A price has changed on a vehicle record. | Read and update the price data. |
| PhotoChange | Photos have been modified on a vehicle. | Follow the photo urls in the data and re-download to your server all new photos. |
| VideosChange | A vehicle video has been added or changed. | Follow the video URL to retrieve the latest video asset. |
| CommentsChange | The seller’s notes have changed for a vehicle. | Read and update the seller’s notes data. |
| RecordChange | A general element outside of what other notifications specifically mention has been changed on a vehicle record. | Read and update the entire data set on a vehicle record. |
| DeleteRecord | A dealer has removed a vehicle from inventory. | Delete the vehicle specified. |
You may choose which of the notifications to respond to and how you would like to respond to each notification. You may ignore notifications as well. You will receive all of these notifications if you subscribe to a dealer topic.
Unsubscribing from Notifications
If at any point you wish to stop receiving notifications, there are a couple of options to stop notification delivery.- 1. You may use the API call to unsubscribe from a dealer topic to stop the notifications about an individual dealer
- 2. You may use the API call to delete your partner notification setup entirely. This will stop all notifications for all dealer topics.
- 3. Each notification contains an unsubscribe URL that you may visit to stop future notifications for the dealer. This is similar to the Unsubscribe Dealer API call.
That is all that is takes to get started with notifications.
Listener Sample Code
String snsMessageType = hh.getRequestHeader("x-amz-sns-message-type").get(0);
SnsNotificationEntity snsNotificationEntity = request.getRequestEntity();
switch (_snsMessageType) {
case "SubscriptionConfirmation": {
String subscribeURL = snsNotificationEntity.subscribeURL;
// visit url
HttpUtil.visitUrl(subscribeURL);
break;
}
case "Notification": {
String notificationType = snsNotificationEntity.subject;
String vehicleURL = snsNotificationEntity.message;
// your implementation goes here
break;
}
}
class SnsNotificationEntity {
String type;
String messageId;
String token;
String topicArn;
String message;
String subscribeURL;
Timestamp timestamp;
String signatureVersion;
String signature;
String signingCertURL;
String subject;
}
Live Stream Implementation
Visit the url below to see your notifcations live!- http://api.netlook.com/api/rest/livestream/v1/partners/[your_partner_client_id]/launch