{"_id":"5bbba59ae4d9ee00035c24c4","project":"59f79e3c584eb200345ceafc","version":{"_id":"5ba178b00a916500030c6a21","project":"59f79e3c584eb200345ceafc","__v":24,"forked_from":"59f79e3c584eb200345ceaff","createdAt":"2015-09-17T03:47:20.956Z","releaseDate":"2015-09-17T03:47:20.956Z","categories":["5ba178b00a916500030c69a2","5ba178b00a916500030c69a3","5ba178b00a916500030c69a4","5ba178b00a916500030c69a5","5ba178b00a916500030c69a6","5ba178b00a916500030c69a7","5ba178b00a916500030c69a8","5ba178b00a916500030c69a9","5ba178b00a916500030c69aa","5ba178b00a916500030c69ab","5ba178b00a916500030c69ac","5afb6888212c690003ae3d3b","5ba178b00a916500030c69ad","5ba178b00a916500030c69ae","5ba2dcbc99f53f0003b97e2c","5babd73fa0ab3e0003ead030","5bb4038be7222e000334dd97","5bb55954478c1300031a44c2","5bb665a1607307000327c81e","5bb6f90229a7fb0003a0650d","5bb7f9bc29a7fb0003a07ac1","5bba58bd7ba7710003bd901d","5bba6dac7ba7710003bd908d","5bba6e257ba7710003bd9090","5bbac87810189c0003e619ea","5bbb9d02b5862c00036266b2","5bbbadb6219c3e000376c2de","5bc417751d1b0000182bf7f6","5bc59e3b2a5b4f0044db5b97","5bc7bbce2262cc0041f6eff2","5bce6a3580a7250031199f34","5bcfac2c4082510019f2d91b","5bcfac3757bed90030e45d68","5bcfac45d305bc0049941539","5bd2a43548bb6f00289c8fad","5bd3a42a026ebe001f66259e","5bd9d5afffe003005b02f97b","5becb7ee85c6b300557662b6"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":false,"codename":"","version_clean":"3.2.0","version":"3.2"},"category":{"_id":"5bbb9d02b5862c00036266b2","project":"59f79e3c584eb200345ceafc","version":"5ba178b00a916500030c6a21","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2018-10-08T18:08:02.170Z","from_sync":false,"order":7,"slug":"ledgering-iou","title":"Ledgering (IOU)"},"user":"5a68eb6970ea610012bfb924","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-10-08T18:44:42.948Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","examples":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"Information in our system is constantly changing and updating, long after API calls have been made. A user could be flagged on a sanctions list, a node’s balance could update after a payment has posted, or a transaction could be queued a little while after the transaction was created. It is important to keep track of these updates, not only for your application, but also to update your users and take action if needed.\n\n##HMAC\n\n\nEvery webhook will be signed with HMAC.\n\nIf you do not know what HMAC is --- it is a protocol that helps you judge the authenticity of the received message. This comes in handy when you want to quickly find out whether the webhook was sent by SynapseFI or a malicious/notorious party. Please see this [Subscription](https://docs.synapsefi.com/docs/subscriptions) resource for more information and example.\n\n\n##What is a Subscription?\n\n\nA subscription is exactly what it sounds like -- to create a subscription means that you are “subscribing” to updates. If this doesn’t make sense, maybe think of it as a newspaper subscription. If you wanted to stay updated on current events, you would subscribe to your local paper, and you would receive the latest stories as they develop. To create a subscription, you would just need to provide the URL you would like your updates delivered to, and the scopes you would like to subscribe to. To continue the newspaper analogy, the URL would be the address that you would like your paper sent to, and the “scopes” would be the specific topics you would like to stay updated on -- news, sports, the comic section, or in our case, users, nodes and transactions.\n\n##What is a Webhook?\n\n\nIf a subscription can be likened to a newspaper subscription, the webhook would be the newspaper itself, with all the content that you’ve requested. A webhook contains the most updated version of a user. To learn more about how to read a webhook, skip to this part here. (link to dissecting a webhook section)\n\n##API Endpoint\nhttps://uat-api.synapsefi.com/v3.1/subscriptions\n\n##PATH PARAMETER##\n[block:html]\n{\n  \"html\": \"<div class=\\\"api-manager\\\"><div class=\\\"param-table\\\"><div class=\\\"table\\\"><div class=\\\"tr\\\"><div class=\\\"td param\\\"> <strong>url<span class=\\\"colon\\\">:</span> </strong><div class=\\\"required\\\">required</div></div><div class=\\\"td\\\"> <strong class=\\\"param-type\\\">string</strong><div marked=\\\"\\\" class=\\\"ng-isolate-scope\\\"><p>Webhook URL</p></div></div></div><div class=\\\"tr\\\"><div class=\\\"td param\\\"> <strong>scope<span class=\\\"colon\\\">:</span> </strong><div class=\\\"required\\\">required</div></div><div class=\\\"td\\\"> <strong class=\\\"param-type\\\">array of strings</strong><div marked=\\\"\\\" class=\\\"ng-isolate-scope\\\"><p>Scope of the subscription</p></div></div></div></div></div></div>\"\n}\n[/block]\n##WEBHOOK USER SCOPE\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Scope\",\n    \"h-1\": \"Effect\",\n    \"0-0\": \"NODE|POST\",\n    \"1-0\": \"NODE|PATCH\",\n    \"2-0\": \"\",\n    \"3-0\": \"NODE|PATCH\",\n    \"4-0\": \"TRANS|POST\",\n    \"5-0\": \"TRAN|PATCH\",\n    \"0-1\": \"Whenever a Node is created with your gateway credentials, you will receive a webhook.\",\n    \"1-1\": \"Whenever a node is updated with your gateway credentials, you will receive a webhook.\",\n    \"2-1\": \"Whenever a node is created for a user registered with your gateway, you will receive a webhook.\",\n    \"3-1\": \"Whenever a node linked to a registered user is updated, you will receive a webhook.\",\n    \"4-1\": \"Whenever a transaction is created with your gateway credentials, you will receive a webhook.\",\n    \"5-1\": \"Whenever a transaction created with your gateway credentials is updated, you will receive a webhook.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n##Example Request\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /v3.1/subscriptions HTTP/1.1\\nHost: uat-api.synapsefi.com\\nX-SP-GATEWAY: client_id_2bb1e412edd311e6bd04e285d6015267|client_secret_2bb1e714edd311e6bd04e285d6015267\\nContent-Type: application/json\\n\\n{\\n  \\\"scope\\\": [\\n    \\\"NODE|POST\\\",\\n    \\\"NODE|PATCH\\\"\\n  ],\\n  \\\"url\\\": \\\"https://requestb.in/zp216zzp\\\"\\n}\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n## Example Successful 200 Response\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"_id\\\": \\\"589b6adec83e17002122196c\\\",\\n    \\\"_links\\\": {\\n        \\\"self\\\": {\\n            \\\"href\\\": \\\"https://uat-api.synapsefi.com/v3.1/subscriptions/589b6adec83e17002122196c\\\"\\n        }\\n    },\\n    \\\"_v\\\": 2,\\n    \\\"client_id\\\": \\\"589acd9ecb3cd400fa75ac06\\\",\\n    \\\"is_active\\\": true,\\n    \\\"scope\\\": [\\n        \\\"NODE|POST\\\",\\n        \\\"NODE|PATCH\\\"\\n    ],\\n    \\\"url\\\": \\\"https://requestb.in/zp216zzp\\\"\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n##Webhook Logistics\n\n\nIf for some reason we fail to deliver a webhook to you, we will continue trying to send the request every hour until we are successful in delivering the webhook, up to 24 hours. After that, we will log the webhook and make it available for viewing on our dashboard. That way, even if we fail to deliver the request, you can still access the original request and the reason as to why the webhook failed.\n\nA webhook delivery is considered a failure if your server does not respond with one of the following HTTP codes: 200, 204, 400, 404, 405\n\n##Things to Monitor\n\n\n* **Account Status: Webhooks will alert you when an account’s status changes. This is helpful if a user’s account is locked or updated.\n\n* **Negative Balances: Balances can go negative due to returns and chargebacks. When this happens, please prompt the user to fund their account. Please be aware that we reconcile negative balances from your reserve account at the end of each month. \n\n* **Low Balances: If a user wants an account to maintain a minimum balance, you can monitor the balance and send automatic reminders to your users to fund the account when it needs to be topped up.\n\n* **Available WIthdrawals: Pay attention to available_withdrawals. Once this hits 0, you will not be able to withdraw from the account until the next calendar month begins.","excerpt":"Get updates on any changes to the ledger accounts","slug":"subscribe-to-ledgering-webhooks","type":"basic","title":"Subscribe to Ledger Webhooks"}

Subscribe to Ledger Webhooks

Get updates on any changes to the ledger accounts

Information in our system is constantly changing and updating, long after API calls have been made. A user could be flagged on a sanctions list, a node’s balance could update after a payment has posted, or a transaction could be queued a little while after the transaction was created. It is important to keep track of these updates, not only for your application, but also to update your users and take action if needed. ##HMAC Every webhook will be signed with HMAC. If you do not know what HMAC is --- it is a protocol that helps you judge the authenticity of the received message. This comes in handy when you want to quickly find out whether the webhook was sent by SynapseFI or a malicious/notorious party. Please see this [Subscription](https://docs.synapsefi.com/docs/subscriptions) resource for more information and example. ##What is a Subscription? A subscription is exactly what it sounds like -- to create a subscription means that you are “subscribing” to updates. If this doesn’t make sense, maybe think of it as a newspaper subscription. If you wanted to stay updated on current events, you would subscribe to your local paper, and you would receive the latest stories as they develop. To create a subscription, you would just need to provide the URL you would like your updates delivered to, and the scopes you would like to subscribe to. To continue the newspaper analogy, the URL would be the address that you would like your paper sent to, and the “scopes” would be the specific topics you would like to stay updated on -- news, sports, the comic section, or in our case, users, nodes and transactions. ##What is a Webhook? If a subscription can be likened to a newspaper subscription, the webhook would be the newspaper itself, with all the content that you’ve requested. A webhook contains the most updated version of a user. To learn more about how to read a webhook, skip to this part here. (link to dissecting a webhook section) ##API Endpoint https://uat-api.synapsefi.com/v3.1/subscriptions ##PATH PARAMETER## [block:html] { "html": "<div class=\"api-manager\"><div class=\"param-table\"><div class=\"table\"><div class=\"tr\"><div class=\"td param\"> <strong>url<span class=\"colon\">:</span> </strong><div class=\"required\">required</div></div><div class=\"td\"> <strong class=\"param-type\">string</strong><div marked=\"\" class=\"ng-isolate-scope\"><p>Webhook URL</p></div></div></div><div class=\"tr\"><div class=\"td param\"> <strong>scope<span class=\"colon\">:</span> </strong><div class=\"required\">required</div></div><div class=\"td\"> <strong class=\"param-type\">array of strings</strong><div marked=\"\" class=\"ng-isolate-scope\"><p>Scope of the subscription</p></div></div></div></div></div></div>" } [/block] ##WEBHOOK USER SCOPE [block:parameters] { "data": { "h-0": "Scope", "h-1": "Effect", "0-0": "NODE|POST", "1-0": "NODE|PATCH", "2-0": "", "3-0": "NODE|PATCH", "4-0": "TRANS|POST", "5-0": "TRAN|PATCH", "0-1": "Whenever a Node is created with your gateway credentials, you will receive a webhook.", "1-1": "Whenever a node is updated with your gateway credentials, you will receive a webhook.", "2-1": "Whenever a node is created for a user registered with your gateway, you will receive a webhook.", "3-1": "Whenever a node linked to a registered user is updated, you will receive a webhook.", "4-1": "Whenever a transaction is created with your gateway credentials, you will receive a webhook.", "5-1": "Whenever a transaction created with your gateway credentials is updated, you will receive a webhook." }, "cols": 2, "rows": 2 } [/block] ##Example Request [block:code] { "codes": [ { "code": "POST /v3.1/subscriptions HTTP/1.1\nHost: uat-api.synapsefi.com\nX-SP-GATEWAY: client_id_2bb1e412edd311e6bd04e285d6015267|client_secret_2bb1e714edd311e6bd04e285d6015267\nContent-Type: application/json\n\n{\n \"scope\": [\n \"NODE|POST\",\n \"NODE|PATCH\"\n ],\n \"url\": \"https://requestb.in/zp216zzp\"\n}", "language": "http" } ] } [/block] ## Example Successful 200 Response [block:code] { "codes": [ { "code": "{\n \"_id\": \"589b6adec83e17002122196c\",\n \"_links\": {\n \"self\": {\n \"href\": \"https://uat-api.synapsefi.com/v3.1/subscriptions/589b6adec83e17002122196c\"\n }\n },\n \"_v\": 2,\n \"client_id\": \"589acd9ecb3cd400fa75ac06\",\n \"is_active\": true,\n \"scope\": [\n \"NODE|POST\",\n \"NODE|PATCH\"\n ],\n \"url\": \"https://requestb.in/zp216zzp\"\n}\n", "language": "json" } ] } [/block] ##Webhook Logistics If for some reason we fail to deliver a webhook to you, we will continue trying to send the request every hour until we are successful in delivering the webhook, up to 24 hours. After that, we will log the webhook and make it available for viewing on our dashboard. That way, even if we fail to deliver the request, you can still access the original request and the reason as to why the webhook failed. A webhook delivery is considered a failure if your server does not respond with one of the following HTTP codes: 200, 204, 400, 404, 405 ##Things to Monitor * **Account Status: Webhooks will alert you when an account’s status changes. This is helpful if a user’s account is locked or updated. * **Negative Balances: Balances can go negative due to returns and chargebacks. When this happens, please prompt the user to fund their account. Please be aware that we reconcile negative balances from your reserve account at the end of each month. * **Low Balances: If a user wants an account to maintain a minimum balance, you can monitor the balance and send automatic reminders to your users to fund the account when it needs to be topped up. * **Available WIthdrawals: Pay attention to available_withdrawals. Once this hits 0, you will not be able to withdraw from the account until the next calendar month begins.