Synapse Developer Hub

Welcome to the Synapse Developer Hub. Here you will find comprehensive guides and documentation to help you start working with the Synapse API as quickly as possible. If you need any assistance, we are always here to help!

Support

Recent Posts

Archive

Subscribe to User Webhooks

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.

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.