Postback (WebHooks)

The Postback API sends a POST request with a JSON payload to the registered postback_url of your app when an order's status changes. This enables you to get arbitrary updates to your orders reliably, irrespective of when they happen (COMPLETE, CANCEL, REJECTED, UPDATE). An UPDATE postback is triggered when an open order is modified or when there's a partial fill. This can be used to track trades.

Note

This Postback API is meant for platforms and public apps where a single api_key will place orders for multiple users. Only orders placed using the app's api_key are notified.

For individual developers, Postbacks over WebSocket is recommended, where, orders placed for a particular user anywhere, for instance, web, mobile, or desktop platforms, are sent.

The JSON payload is posted as a raw HTTP POST body. You will have to read the raw body and then decode it.

Sample payload

{
    "order_id": "16032300017157",
    "exchange_order_id": "511220371736111",
    "placed_by": "AB0012",
    "status": "COMPLETE",
    "status_message": "",

    "tradingsymbol": "TATAMOTORS",
    "exchange": "NSE",
    "order_type": "MARKET",
    "transaction_type": "SELL",
    "validity": "DAY",
    "product": "CNC",

    "average_price": 376.35,
    "price": 376.35,
    "quantity": 1,
    "filled_quantity": 1,
    "unfilled_quantity": 0,
    "trigger_price": 0,
    "status_message": "",
    "user_id": "AB0012",
    "order_timestamp": "2015-12-20 15:01:43",
    "exchange_timestamp": "2015-12-20 15:01:43",
    "checksum": "5aa3f8e3c8cc41cff362de9f73212e28"
}

Checksum

The JSON payload comes with a checksum, which is the SHA-256 hash of (order_id + timestamp + api_secret). For every Postback you receive, you should compute this checksum at your end and match it with the checksum in the payload. This is to ensure that the update is being POSTed by Kite Connect and not by an unauthorised entity, as only Kite Connect can generate a checksum that contains your api_secret.

Payload attributes

attribute  
order_idstring Unique order ID
exchange_order_idnull, string Exchange generated order id. Orders that don't reach the exchange have null ids
placed_bystring ID of the user that placed the order. This may different from the user's id for orders placed outside of Kite, for instance, by dealers at the brokerage using dealer terminals.
statusstring Current status of the order. The possible values are COMPLETE, REJECTED, CANCELLED, and UPDATE.
tradingsymbolstring Exchange tradingsymbol of the of the instrument
exchangestring Exchange
transaction_typestring BUY or SELL
validitystring Order validity
average_pricefloat Average price at which the order was executed (only for COMPLETE orders)
pricefloat Price at which the order was placed (LIMIT orders)
quantityint Quantity ordered
filled_quantityint Quantity that's been filled
trigger_pricefloat Trigger price (for SL, SL-M, CO orders)
status_messagenull, string Textual description of the order's status. Failed orders come with human readable explanation
user_idstring ID of the user for whom the order was placed.
order_timestampstring Timestamp at which the order was registered by the API
checksumstring SHA-256 hash of (order_id + timestamp + api_secret)

Note

Postback API works even when the user is not logged in. Just make sure you validate the checksum value to ensure that the update is indeed coming from Kite Connect.