Webhooks
Webhook enables partners to receive push notifications to their server as and when the events like single stock (or basket) order update and holding import occur.
Overview ⚓️
Webhook is an event-driven communication method where a webhook provider (smallcase Gateway backend) delivers data to a webhook consumer (Gateway partner backend) as and when an event occurs. A more traditional way to get almost real-time data was for consumers to frequently poll the provider. However, webhooks are considered more efficient and reliable.
smallcase Gateway Webhook enables partners to receive push notifications to their server as and when the events like single stock (or basket) order update and holding import occur.
Consuming a Webhook
- Create a public API endpoint in your backend which will listen for new data that would be delivered by the smallcase Gateway backend.
- Once the API is up & running, share the endpoint URL with the smallcase Gateway team so that we can register in our system.
Authentication
While the API endpoint exposed should be publicly available for smallcase Gateway to post updates on, the requests should to be authenticated before processing the updates.
We use HMAC-SHA256 algorithm for generating checksum. This allows your webhook endpoint to authenticate the request being made.
The request payload has a checksum key which is the base16 encoded HMAC generated with:
- algorithm =
SHA256 - key = shared api secret
- message =
payload's timestamp+payload's smallcaseAuthId
For every hit that you receive, checksum should be created at your end and matched with payload.checksum.
Dino Chiesa's HMAC generator is open-sourced playground (Note: pasting secrets on third-party website is dangerous. Take utmost caution!).
smallcase Gateway Webhooks
smallcase Gateway offer webhooks for the following use cases -
- Stocks order
- Holdings Import
- Pending user action (smallcase orders)
Stocks order
Sample payload
{
"batchId":"61c04af1010a116fe77872e8",
"notes":"your-notes-goes-here",
"buyAmount":145.99,
"sellAmount":0,
"quantity":1,
"filled":1,
"status":"COMPLETED",
"variety":"regular",
"completedDate":"2021-12-20T09:20:53.083Z",
"orders":[
{
"status":"COMPLETE",
"quantity":1,
"tradingsymbol":"REDINGTON",
"transactionType":"BUY",
"averagePrice":145.99,
"exchange":"NSE",
"orderType":"MARKET",
"product":"CNC",
"filledQuantity":1,
"exchangeOrderId":"61c04ad76979eb99b328618a61c04af26979eb99b328618e"
}
],
"unplaced":[
],
"transactionId":"TRX_7d596e3243de42bd9b391e3a0c3ba2ba",
"broker":"kite",
"smallcaseAuthId":"61c04aee2d6366d5c97994ba",
"timestamp":"2021-12-20T09:20:53.130Z",
"checksum":"bb9f2afcf135ddafd9ad127d9a901bc327eda6f2ffa25ccc91d0fd061816a958"
}
Can there be multiple hits for a transactionId?
Yes. For every transaction, the webhook will be called on order placement, and thereafter on transaction's batch status update (if any).
The batch status can update for transaction with batch status in "PLACED" state (orderBatches[].status = PLACED).
For example, a user placed an AMO order, and on the next trading session the order got executed. The first webhook event would be as soon as the user confirms the order. And the next event would be fired when the order got executed / cancelled.
Holdings Import
Sample payload
{
"success": true,
"errors": null,
"data": {
"smallcases": {
"public": [
{
"scid": "SCAW_0001",
"name": "All Weather Investing",
"investmentDetailsURL": "https://smallcase.zerodha.com/details/5f2d22636678954954f29a2d?",
"shortDescription": "Diversify with equity, gold & fixed income ETFs for recession-proof investing",
"imageUrl": "https://assets.smallcase.com/images/smallcases/200/SCAW_0001.png",
"stats": {
"currentValue": 4921.89,
"totalReturns": -36.65253999999927
},
"constituents": [
{
"ticker": "NIFTYBEES",
"shares": 10
},
{
"ticker": "JUNIORBEES",
"shares": 3
},
{
"ticker": "LIQUIDBEES",
"shares": 1
},
{
"ticker": "GOLDBEES",
"shares": 39
}
]
}
],
"private": {
"stats": {
"currentValue": 57.31,
"totalReturns": 1.3100000000000023
}
}
},
"securities": [
{
"holdings": {
"quantity": 4,
"averagePrice": 36.68
},
"positions": {
"nse": {
"quantity": 1,
"averagePrice": 34.1
},
"bse": {
"quantity": 1,
"averagePrice": 34.1
}
},
"transactableQuantity": 5,
"smallcaseQuantity": 2,
"nseTicker": "J&KBANK",
"bseTicker": "J&KBANK",
"isin": "INE168A01041",
"name": "Jammu and Kashmir Bank Ltd"
},
{
"holdings": {
"quantity": 1,
"averagePrice": 28.4
},
"positions": {
"nse": {
"quantity": 0,
"averagePrice": 0
},
"bse": {
"quantity": 0,
"averagePrice": 0
}
},
"transactableQuantity": 1,
"smallcaseQuantity": 0,
"nseTicker": "MASPTOP50",
"bseTicker": "MASPTOP50",
"isin": "INF769K01HP3",
"name": "Mirae Asset S&P 500 Top 50 ETF"
},
{
"holdings": {
"quantity": 1,
"averagePrice": 10.53
},
"positions": {
"nse": {
"quantity": 0,
"averagePrice": 0
},
"bse": {
"quantity": 0,
"averagePrice": 0
}
},
"transactableQuantity": 1,
"smallcaseQuantity": 0,
"nseTicker": "AXISBPSETF",
"bseTicker": null,
"isin": "INF846K01Z04",
"name": "Axis AAA Bond Plus SDL ETF-2026 Matur. Reg. Growth"
},
{
"holdings": {
"quantity": 1,
"averagePrice": 9.8
},
"positions": {
"nse": {
"quantity": 0,
"averagePrice": 0
},
"bse": {
"quantity": 0,
"averagePrice": 0
}
},
"transactableQuantity": 1,
"smallcaseQuantity": 0,
"nseTicker": "SUZLON",
"bseTicker": "SUZLON",
"isin": "INE040H01021",
"name": "Suzlon Energy Ltd"
},
{
"holdings": {
"quantity": 1,
"averagePrice": 48.5
},
"positions": {
"nse": {
"quantity": 0,
"averagePrice": 0
},
"bse": {
"quantity": 0,
"averagePrice": 0
}
},
"transactableQuantity": 1,
"smallcaseQuantity": 0,
"nseTicker": "ICICIB22",
"bseTicker": "ICICIB22",
"isin": "INF109KB15Y7",
"name": "Bharat 22 ETF"
},
{
"holdings": {
"quantity": 1,
"averagePrice": 36.05
},
"positions": {
"nse": {
"quantity": 0,
"averagePrice": 0
},
"bse": {
"quantity": 0,
"averagePrice": 0
}
},
"transactableQuantity": 1,
"smallcaseQuantity": 0,
"nseTicker": "PNB",
"bseTicker": "PNB",
"isin": "INE160A01022",
"name": "Punjab National Bank"
}
],
"updating": false,
"lastUpdate": "2022-03-24T11:33:52.986Z",
"snapshotDate": "2022-03-24T11:24:00.871Z",
"smallcaseAuthId": "6195e288360acf9ebc060d23",
"broker": "groww",
"transactionId": "TRX_06726c28769e44b8920bd6eb5bbeef17",
"timestamp": "2022-03-24T11:33:53.091Z",
"checksum": "fe7a17d4f82831918a1363af080f5a92f382efa872b1a2a7823964b6bf7e3285"
}
}
{
"smallcases":{
"public":[
{
"scid":"SCAW_0001",
"name":"All Weather Investing",
"investmentDetailsURL":"https://smallcase.zerodha.com/details/5f7ec65caf9e9e3ce695bc4a?",
"shortDescription":"Diversify with equity, gold & fixed income ETFs for recession-proof investing",
"imageUrl":"https://assets.smallcase.com/images/smallcases/200/SCAW_0001.png",
"stats":{
"currentValue":4308.15,
"totalReturns":727.0412199999994
},
"constituents":[
{
"ticker":"GOLDBEES",
"shares":23
},
{
"ticker":"JUNIORBEES",
"shares":3
},
{
"ticker":"NIFTYBEES",
"shares":6
},
{
"ticker":"LIQUIDBEES",
"shares":1
}
]
},
{
"scid":"SCNM_0010",
"name":"The Great Indian Middle Class - Custom",
"investmentDetailsURL":"https://smallcase.zerodha.com/details/60d2bbb999a5de24eba97ab4?",
"shortDescription":"Companies focused on the growing middle class. Running India's consumption engine",
"imageUrl":"https://assets.smallcase.com/images/smallcases/200/SCNM_0010.png",
"stats":{
"currentValue":0,
"totalReturns":0
},
"constituents":[
]
}
],
"private":[
]
},
"securities":{
"holdings":[
{
"ticker":"INFY",
"shares":14,
"name":"Infosys Ltd",
"exchange":"NSE",
"averagePrice":1474.2927272727275
},
{
"ticker":"MRF",
"shares":10,
"name":"MRF Ltd",
"exchange":"NSE",
"averagePrice":66105.91
},
{
"ticker":"ADROITINFO",
"shares":2,
"name":"Adroit Infotech Ltd",
"exchange":"NSE",
"averagePrice":7
},
{
"ticker":"DRREDDY",
"shares":14,
"name":"Dr Reddy's Laboratories Ltd",
"exchange":"NSE",
"averagePrice":4097.744285714286
},
{
"ticker":"ITC",
"shares":29,
"name":"ITC Ltd",
"exchange":"NSE",
"averagePrice":200.40530153724868
},
{
"ticker":"ASIANPAINT",
"shares":7,
"name":"Asian Paints Ltd",
"exchange":"NSE",
"averagePrice":2118.8002857142856
}
]
},
"updating":false,
"lastUpdate":"2021-12-20T09:27:03.014Z",
"snapshotDate":"2021-12-20T09:27:03.014Z",
"smallcaseAuthId":"5ef33705f610f80b5453b319",
"broker":"iifl",
"notes":"your-notes-goes-here",
"transactionId":"TRX_7c30e4d9904f4f79b692f281a83cdc1f",
"timestamp":"2021-12-20T09:27:03.059Z",
"checksum":"d04a000b47c44bf6a721c829b8a8815b8470b2b5c767112b92f82943ea712fdd"
}
Pending user action (smallcase orders)
A user invested in a smallcase can have pending actions to be performed. These can be -
-
FIX ACTION : This triggers a repair order on smallcase. In a repair order, all the unfilled stocks of the previous transaction are attempted again as a fresh order on the same invested smallcase.
-
REBALANCE ACTION : smallcases are reviewed & updated on a regular basis. Once a rebalance update is pushed, a rebalance order is added to the invested smallcase.
-
SIP ACTION : A user can set SIP on an invested smallcase. On the due date, a SIP order is added to the invested smallcase.
Learn more about pending actions? Check this guide!
Partners can use this pending actions data to communicate the same to their users. Everyday smallcase Gateway will hit your pending action webhook for all relevant gateway users (one hit per user). The pending action stays till the user acts upon the action. You will receive the same action everyday until user acts upon it, or new action of same type is added.
{
"eventType": "USER.PENDING_ACTIONS",
"timestamp": "2021-06-01T09:28:14.561Z",
"checksum": "5a60d322fd0c1fcb51bf3e272c18d94016e5a550ec1fad4189ef221034b11175",
"data": {
"smallcaseAuthId": "5e96ebd5e5520425f7433610",
"investments": [
{
"iscid": "5e972a5fbd687e4da5f00c47",
"smallcaseName": "Magic Formula",
"scid": "SCMO_0006",
"fixAction": {
"date": "2020-04-16T06:51:37.240Z",
"filled": 7,
"quantity": 11,
"originalLabel": "BUY"
}
},
{
"iscid": "5e971fdfbd687e4da5f00c3f",
"smallcaseName": "Low Risk - Smart Beta",
"scid": "SCSB_0003",
"rebalanceAction": {
"label": "Quarterly Update: Weights Rebalance",
"rationale": "There are no changes in the stocks or weighting scheme of this smallcase for this quarter. The weights in which you hold stocks might have changed due to changing prices, rebalance this smallcase to move back to the prescribed weights",
"date": "2020-06-18T00:00:00.000Z"
}
},
{
"iscid": "5e980b61dba2e16cf3e6d04d",
"smallcaseName": "Quantum",
"scid": "GATEMO_0001",
"sipAction": {
"frequency":"1m",
"amount":85.64,
"scheduledDate":"2021-04-27T00:00:00.000Z",
"type": "MANUAL"
}
}
]
}
}
Sample payload
FAQs
-
Is there any retry mechanism, in case our webhook could not capture data on the first try?
Yes, we have a retry mechanism in place which would retry hitting the webhook URL after a certain duration -
i. First retry after 15 minutes
ii. Second retry after 24 hours
iii. Final retry after 48 hours -
There's no Webhook support for our use case. Is it possible to add support?
We are always open to exploring use cases. Let us know your use case for which you need webhook support, we will definitely see what can be done.
Updated about 1 month ago