Skip to content

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

{
    "user_id":"AB0012", 
    "app_id":1234,
    "checksum":"1ebfd6d8a3d40c36722b3bfbf",
    "placed_by":"AB0012",
    "order_id":"210709003691276",
    "exchange_order_id":"1300000015536862",
    "parent_order_id":null,
    "status":"UPDATE",
    "status_message":null,
    "status_message_raw":null,
    "order_timestamp":"2021-07-09 15:00:57",
    "exchange_update_timestamp":"2021-07-09 15:00:57",
    "exchange_timestamp":"2021-07-09 15:00:57",
    "variety":"regular",
    "exchange":"NSE",
    "tradingsymbol":"SBIN",
    "instrument_token":779521,
    "order_type":"LIMIT",
    "transaction_type":"BUY",
    "validity":"DAY",
    "product":"MIS",
    "quantity":1,
    "disclosed_quantity":0,
    "price":420,
    "trigger_price":0,
    "average_price":0,
    "filled_quantity":0,
    "pending_quantity":1,
    "cancelled_quantity":0,
    "market_protection":0,
    "meta":{},
    "tag":null,
    "guid":"7831XMQ"
}

Checksum

The JSON payload comes with a checksum, which is the SHA-256 hash of (order_id + order_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
parent_order_idnull, string Order ID of the parent order (only applicable in case of multi-legged orders like CO)
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
instrument_tokenuint32 The numerical identifier issued by the exchange representing the instrument
exchangestring Exchange
order_typestring Order type (MARKET, LIMIT etc.)
transaction_typestring BUY or SELL
validitystring Order validity
varietystring Order variety (regular, amo, co etc.)
productstring Margin product to use for the order
average_pricefloat Average price at which the order was executed (only for COMPLETE orders)
disclosed_quantityint Quantity to be disclosed (may be different from actual quantity) to the public exchange orderbook. Only for equities
pricefloat Price at which the order was placed (LIMIT orders)
quantityint Quantity ordered
filled_quantityint Quantity that has been filled
pending_quantityint Pending quantity for open order
cancelled_quantityint Quantity that had been cancelled
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
exchange_update_timestampstring Timestamp at which an order's state changed at the exchange
exchange_timestampstring Timestamp at which the order was registered by the exchange. Orders that don't reach the exchange have null timestamps
checksumstring SHA-256 hash of (order_id + timestamp + api_secret)
metastring Map of arbitrary fields that the system may attach to an order
tagstring An optional tag to apply to an order to identify it (alphanumeric, max 20 chars)

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.