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.

HMAC

Every webhook will be signed with HMAC.

HMAC 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 resource for more information and examples.

What is a Subscription?

A subscription is exactly what it sounds like -- to create a subscription means that you are “subscribing” to updates. 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.

API Endpoint

https://uat-api.synapsefi.com/v3.1/subscriptions

PATH PARAMETER

url:
required
string

Webhook URL

scope:
required
array of strings

Scope of the subscription

WEBHOOK USER SCOPE

Scope
Effect

USER|POST

Whenever a user is created with your gateway credentials, you will receive a webhook.

USER|PATCH

Whenever a user linked to your gateway is updated, you will receive a webhook.

Example Request

POST /v3.1/subscriptions HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-GATEWAY: client_id_2bb1e412edd311e6bd04e285d6015267|client_secret_2bb1e714edd311e6bd04e285d6015267
Content-Type: application/json

{
  "scope": [
    "USERS|POST",
    "USER|PATCH"
  ],
  "url": "https://requestb.in/zp216zzp"
}
body = {
  "scope": [
    "USERS|POST",
    "USER|PATCH"
  ],
  "url": "https://requestb.in/zp216zzp"
}

client.create_subscriptions(body)
body = {
  "scope": [
    "USERS|POST",
    "USER|PATCH"
  ],
  "url": "https://requestb.in/zp216zzp"
}

client.createSubscription(body);
body = {
  "scope": [
    "USERS|POST",
    "USER|PATCH"
  ],
  "url": "https://requestb.in/zp216zzp"
}

client.create_subscriptions(scope: body)
$body= (object) [
     scope" => [
       "USERS|POST",
       "USER|PATCH",
       "NODES|POST",
       "NODE|PATCH",
       "TRANS|POST",
       "TRAN|PATCH"
     ],
      'url' => 'https://requestb.in/zp216zzp'
  ];

$client->create_subscription( $body);
scopeSettings := `{
  "scope": [
    "USERS|POST",
    "USER|PATCH",
    ....
  ],
  "url": "https://requestb.in/zp216zzp"
}`

data, err := client.CreateSubscription(scopeSettings, "")

Example Successful 200 Response

{
    "_id": "589b6adec83e17002122196c",
    "_links": {
        "self": {
            "href": "https://uat-api.synapsefi.com/v3.1/subscriptions/589b6adec83e17002122196c"
        }
    },
    "_v": 2,
    "client_id": "589acd9ecb3cd400fa75ac06",
    "is_active": true,
    "scope": [
        "USERS|POST",
        "USER|PATCH"
    ],
    "url": "https://requestb.in/zp216zzp"
}

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

Webhooks will expire 15 days after creation.

Use Cases for Webhooks

  • 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.