{"_id":"5bb3bb5d4a624b0003aee759","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":"5babd73fa0ab3e0003ead030","project":"59f79e3c584eb200345ceafc","version":"5ba178b00a916500030c6a21","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2018-09-26T19:00:15.801Z","from_sync":false,"order":2,"slug":"userskyc","title":"Users/KYC"},"user":"5a68eb6970ea610012bfb924","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-10-02T18:39:25.798Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","examples":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":10,"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[block:api-header]\n{\n  \"title\": \"HMAC\"\n}\n[/block]\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/v3.2/docs/subscribe-to-webhooks) resource for more information and examples.\n\n[block:api-header]\n{\n  \"title\": \"What is a Subscription?\"\n}\n[/block]\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[block:api-header]\n{\n  \"title\": \"What is a Webhook?\"\n}\n[/block]\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\": \"USER|POST\",\n    \"1-0\": \"USER|PATCH\",\n    \"2-0\": \"\",\n    \"3-0\": \"NODE|PATCH\",\n    \"4-0\": \"TRANS|POST\",\n    \"5-0\": \"TRAN|PATCH\",\n    \"0-1\": \"Whenever a user is created with your gateway credentials, you will receive a webhook.\",\n    \"1-1\": \"Whenever a user linked to your gateway is updated, 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    \\\"USERS|POST\\\",\\n    \\\"USER|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        \\\"USERS|POST\\\",\\n        \\\"USER|PATCH\\\"\\n    ],\\n    \\\"url\\\": \\\"https://requestb.in/zp216zzp\\\"\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Webhook Logistics\"\n}\n[/block]\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[block:api-header]\n{\n  \"title\": \"Use Cases for Webhooks\"\n}\n[/block]\n* **Negative Balances:** Balances can go negative due to returns, chargebacks and offline authorization for cards. When this happens, please prompt the user to fund their account. Please be aware that we reconcile open negative balances from your reserve account once a month during billing.\n\n* **Low Balances:** If you need this 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* **Account Status:** Webhooks will alert you when a deposit account’s status changes. This is helpful if a user’s deposit account is locked or updated.","excerpt":"Subscribe to webhooks to get user updates","slug":"subscribe-to-user-webhooks","type":"basic","title":"Subscribe to User Webhooks"}

Subscribe to User Webhooks

Subscribe to webhooks to get user updates

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. [block:api-header] { "title": "HMAC" } [/block] 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/v3.2/docs/subscribe-to-webhooks) resource for more information and examples. [block:api-header] { "title": "What is a Subscription?" } [/block] 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. [block:api-header] { "title": "What is a Webhook?" } [/block] 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": "USER|POST", "1-0": "USER|PATCH", "2-0": "", "3-0": "NODE|PATCH", "4-0": "TRANS|POST", "5-0": "TRAN|PATCH", "0-1": "Whenever a user is created with your gateway credentials, you will receive a webhook.", "1-1": "Whenever a user linked to your gateway is updated, 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 \"USERS|POST\",\n \"USER|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 \"USERS|POST\",\n \"USER|PATCH\"\n ],\n \"url\": \"https://requestb.in/zp216zzp\"\n}\n", "language": "json" } ] } [/block] [block:api-header] { "title": "Webhook Logistics" } [/block] 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 [block:api-header] { "title": "Use Cases for Webhooks" } [/block] * **Negative Balances:** Balances can go negative due to returns, chargebacks and offline authorization for cards. When this happens, please prompt the user to fund their account. Please be aware that we reconcile open negative balances from your reserve account once a month during billing. * **Low Balances:** If you need this 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. * **Account Status:** Webhooks will alert you when a deposit account’s status changes. This is helpful if a user’s deposit account is locked or updated.