Order Management Notification Service

The Order Management Notification Service provides support for notifications, to be sent from the Flipkart system to the seller system, for any event in an order lifecycle, such as order creation, label creation, order cancellation, and so on. You can use this feature to improve the performance of your application by eliminating additional network and computation costs in polling resources to determine if they have changed.

Notifications can be sent in the following stages of an order lifecycle.

Format: JSON

Notification Description / Use Case
Order Created Sent when an order is placed
Hold Sent when an order item is flagged as “Hold”
UnHold Sent when an order item flagged as “Hold” is released for further processing
Packed Sent when an order item state is changed to “Packed”
Ready To Dispatch Sent when an order item is marked as “Ready to Dispatch”
Pickup Complete Sent when the shipment is picked up by the logistics team
Shipped Sent when an order item is shipped
Delivered Sent when an order item is delivered
Dispatch Dates Changed Sent when the dispatch date is changed
Return Created Sent when a new return request is created
Return Completed Sent when a return is completed
Return Cancelled Sent when a return request is revoked
Cancelled Sent when an approved order is cancelled

Subscribing to Notifications

To use notifications:

The proposed event structure for these notifications contain the following parameters:

Parameter Name Description
eventType The notification type. Possible values: order_item_created, order_item_packed, order_item_to_dispatch, order_item_shipped, order_item_delivered, and so on
source Point of origin of the notification - “flipkart”
timestamp ISO time string
attributes Custom parameters for the event

Notifications Authentication

All Flipkart Notifications are RESTful notifications that send event payloads to the seller system endpoint.

Sellers authenticate to Flipkart API using OAuth credentials (Application ID and Application Secret). Those who wish to listen to notifications must register their notification endpoints with Flipkart. Sellers need a mechanism to validate whether the request originated from Flipkart and not by untrusted sources. Flipkart REST APIs authenticate to seller notification endpoints using a signature-based authentication by using Authorization headers.

Every notification includes headers in the following format:

X_Date : <date_timestamp>
X_Authorization : FKLOGIN  Base64 (OAuth-appid : <fk_signature>)

Here,

  • date_timestamp is the timestamp at which the notification is generated and is in “HTTP-Date” format.

  • fk_signature is generated per request using SHA1 based message digest algorithm with values derived from request as:

    SHA-1 (date_timestamp + notification_http_url + notification_http_method + OAuth-secret)
    

REST endpoints that receive these notifications need to authenticate the request by regenerating the Signature (fk_signature) using the logic above and verifying it with the Authorization (X_Authorization) header. Consider the following example.

Authentication Sample

Seller: PilotSeller

OAuth Appication ID: 6113ca4a-fe05-11e4-a322-1697f925ec7b

OAuth Application Secret: 669a57f4-fe05-11e4-a322-1697f925ec7b

Notification URL: http://seller.api.pilotseller.com/notify/fki POST

Timestamp: 1432026135

Signature:

SHA1(1432026135http://seller.api.pilotseller.com/notify/fkiPOST669a57f4-fe05-11e4-a322-1697f925ec7b) 83762abd87b41e66ddd58320a4e803251e72b776

Authorization Information:

Base64(6113ca4a-fe05-11e4-a322-1697f925ec7b:83762abd87b41e66ddd58320a4e803251e72b776)NjExM2NhNGEtZmUwNS0xMWU0LWEzMjItMTY5N2Y5MjVlYzdiOjgzNzYyYWJkODdiNDFlNjZkZGQ1ODMyMGE0ZTgwMzI1MWU3MmI3NzY=

Headers

X_Date: Tue, 19 May 2015 09:02:15 GMT

X_Authorization:

FKLOGIN NjExM2NhNGEtZmUwNS0xMWU0LWEzMjItMTY5N2Y5MjVlYzdiOjgzNzYyYWJkODdiNDFlNjZkZGQ1ODMyMGE0ZTgwMzI1MWU3MmI3NzY=

Notifications Response

For a notification, the seller application needs to respond with a standard HTTP success status 200, or should throw an error response in the following scenarios only:

  • When the seller system is down
  • If the payload is incorrect

The notification system ensures that the message is sent at least once, but not only once. Hence, it is recommended to add an idempotency check in the client to avoid processing of duplicate notifications.