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

Subscriptions Intro

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 after it was marked verified, 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. You can subscribe to webhooks to receive updates on users, nodes and transactions automatically.

Scope Syntax

Scope tells us when this webhook should be triggered. Following are the ways you can supply scope for subscriptions.

Only one subscription can be enabled for each scope. So if you had multiple subscription objects, we recommend disabling subscriptions that you do not wish to use any longer.

Scope

Effect

NODE|POST

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

NODE|PATCH

Whenever a node is updated with your gateway credentials, you will receive a webhook.

USER|POST

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

USER|PATCH

Whenever a user in your platform is updated, you will receive a webhook.

TRANS|POST

Whenever a transaction is created within your gateway credentials, you will receive a webhook.

TRAN|PATCH

Whenever a transaction is updated with your gateway credentials, you will receive a webhook.

SUBNET|POST

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

SUBNET|PATCH

Whenever a subnet is updated with your gateway credentials, you will receive a webhook.

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.

Testing Webhooks

HMAC FOR WEBHOOKS

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 web hook was sent by SynapsePay or a malicious/notorious party.

The signature is a SHA-1 and SHA-256 HMAC hash of the object_id + your client_id, with the secret key as your client_secret.

Please note that raw should look like this (with +):"563db3fb86c27307d925871f+e3f19e4bd4022c86e7f2"

Not like this (without +):"563db3fb86c27307d925871fe3f19e4bd4022c86e7f2".

Since the sha1 signature is in hex, it should look like this: bce964c20b0c36313d8f7cffc2ff4772d0c96750.

We then take this signature and add it into the header of the request with name X-Synapse-Signature and X-Synapse-Signature-Sha256.

Webhook Format

The webhook always returns a user, node, or transaction object. These are the same as the objects returned by the API responses, with a couple exceptions:

The value of ids are objects storing an $oid, which is the object ID.

The value of dates are objects storing a $date.

If you wish to consume exactly the same responses as you get from the API, look under key _rest. If you also want to see who the object was updated by and what function was used to perform the update, look under webhook_meta.