Callbacks

Callbacks and Main Terminology

Let's first define some main vocabulary related to callbacks that will make the process easier to talk about.

Callback

Shortly put, a “callback” is a POST request sent from Crypto APIs to a customer’s Callback URL when an event they have already subscribed for occurs.

Now with a bit more detail, a “callback” is used to describe an event reaction process where a user receives notifications on certain events by having first subscribed to them in the system. The term has become interchangeable with the word “webhook”, used to describe the same thing. The callback is a way for the system to avoid customers constantly calling the Crypto API to check for an update or event they may be expecting. Callbacks can be very useful for customers who expect, track or want to be notified about the state of transactions on the blockchain.

There are two sides of the callback - the server side and the customer side. The process follows the customer side subscribing for an event on the server side and the server side notifying the customer side when that event is completed.

With Crypto APIs there are endpoints which will lead to callbacks. These include, but are not limited to Blockchain Events and Blockchain Automations.

Callback Events

Definition

Specific processes are considered an “event”. Simply put, an “event” is something that occurs on the Blockchain or Crypto Market. Crypto APIs incorporates various endpoints which hold different characteristics. You can see endpoints that represent events to which users can subscribe for a callback on our API Reference page. Such supported for callback endpoints are displayed with an arrow icon next to them to easily view Callback request parameters and response examples.

Types

There are a number of different event types. As a Callback event the following are considered:

• New Block;
• New Incoming Transaction;
• New Outgoing Transaction;
• New Confirmation;
• Already Forwarded Coins, and more.

Callback URL

Callbacks require what is known as a ”Callback URL”. It is the destination where Crypto APIs sends the callback notification for the event. Setting up this URL is done entirely on the customer’s side and is the first step to setting up a Callback.

Let’s see the main steps the customer needs to take in order to set up their Callback URL:

1. First and foremost, the user must verify a domain they have access to in general. This is done in their Crypto APIs Dashboard. The customer has to upload a unique code, provided to them by the Crypto APIs Dashboard, to the frontend of their website.

2. Afterwards, the customer can click to Verify in the Dashboard. AT that point Crypto APIs will make a request to the specified domain name and check for the code. When it is located, Crypto APIs verifies the domain. If it is not found in the frontend, the domain will not be verified.

After the domain is verified, then the user can set a specific URL destination to serve as the Callback URL.

Example:

Domain to verify: ”mypage.mydomain.com” Callback URL to set: “mypage.mydomain.com/login/callback” Cannot use URL: “mydomain.com/login/callback”

Domain to verify: ”mydomain.com” Callback URL to set: “mydomain.com/login/callback” Cannot use URL: “mypage.mydomain.com/login/callback”

Crypto APIs Callback basics

Crypto APIs Callbacks follow certain basics and the same standard that applies to all callback subscriptions.

• Callback requests sent from Crypto APIs are always POST;
• All Crypto APIs headers must by default incorporate the JSON content type application/json;
• All Crypto API Callbacks incorporate the use of a Callback URL, without exceptions;
• A customer can subscribe for a callback to as many supported events as they want, as many times as needed;
• The callback functionality in Crypto APIs is identical throughout every product and endpoint that supports it;
• The callback request from Crypto APIs to the customer includes the exact information and parameters as requested by the customer when they first set up the subscription, which are included in the data parameter of the code;
• The attribute x-signature is a custom for Crypto APIs parameter, as indicated with the x- in the beginning;
• The structure of the Callback is always the same no matter the subscription or type of event.

Callback standard structure

The callback structure has the following constant parameters:

{
    "apiVersion": "2.0", //**Represents the current Crypto APIa version, which is v2.**
    "referenceId": "2921e3df-c671-4d20-b51b-d176d5c1e43g", //**Represents the unique reference identifier of the callback.**
    "idempotencyKey": "3b3359d0ccdb1d3d3ca8dbaa79cb5395b33c5bc52d782f3ea22904abef45d1j4", //**Specifies a unique ID used by Crypto APIs to recognize consecutive requests with the same data so that not to perform the same operation twice.**
    "data": { //**Includes information and details on the callback, dependent on the customer’s secret.**
        "product": "BLOCKCHAIN_EVENTS", //**Specifies the product for which the event occurs.**
        "event": "BLOCK_MINED", //**Specifies the actual event type, for which the callback subscription was made.
        "item": { //**Includes all customer-specific details for the callback.**
        }
    }
}

API Versions and apiVersion

The structure of the callback the customer will receive depends on the version of the Crypto API. Currently, we use v2. When the user sets a subscription for an event while on v2 of the software, the callback will be returned according to v2 specifics.

Each time we update our API to a next version, the customer would need to reset their event subscriptions so that they correspond to the newest software version currently in use. To do that the customer would need to remove the event subscription and set it up again. Otherwise, the callback response will be received in the format of the older API version it was set up in.

Reference ID and referenceId

The referenceId indicates a reference to the subscription that has been made by the customer. It is a unique code applicable only for that subscription. Each time a customer sets up an automation or event subscription, the corresponding callback always has a parameter referenceId.

Idempotency and idempotentKey

Idempotency represents a process in computing and REST which a server uses to recognize subsequent retries of the same request where the returned result always remains the same. It is a security mechanism for retrying requests without the risk of performing the same operation more than once.

Such risks usually can occur when an API call is for some reason disrupted during processing (e.g. network connection error) and a response is not returned. In such cases the API call would be retried. By including an idempotencyKey in the initial request there is guarantee that the specific action won’t be done more than once.

The idempotencyKey is generated only on the server-end in the use of Crypto APIs Callbacks. It is added to the Callback request and is unique per initial callback request. idempotencyKey values are generated randomly.

All original requests containing an idempotencyKey, along with their body and response status code (both success and error), are saved by the system. After that, any subsequent requests containing the same idempotencyKey will automatically return the same result.

Setting up callbacks

Callbacks combine certain elements and steps needed to be able to create a correct reaction and on-time notification.

Their way of work includes the customer to first set up their callback subscription, and later on, whenever the subscription event occurs, for the Crypto APIs to notify the customer. All steps are taken through API Requests and Responses.

1. Customer sets up Callback URL

   The customer must first have a verified domain and set up Callback URL.

2. Customer subscribes for an event

   After verifying their domain, the customer has to send a request to Crypto APIs in order to subscribe for a callback on a certain event. The customer can subscribe to as many events they want, as many times as they need.

   When the customer sends their request to subscribe for an event the system must return a response. If there is no problem, where otherwise an error would result, the response from Crypto APIs would be “201 New resource successfully created”. Then it is confirmed that the callback subscription for that particular event has been set up.

   If the subscription setup has failed, it will return an error, e.g. Error 409 Conflict. If an error is returned, there is a mistake or issue with the customer’s request. It must be then fixed so that Crypto APIs can return a successful response.

3. Crypto APIs sends the Callback as a request

   Crypto APIs’ responsibility to the customer is to notify them according to their subscription for that particular event or events only when it/they occur. Whenever the event happens Crypto APIs sends a request back to the customer that includes the data on the event, as requested by the customer. This is essentially the “callback” itself. If the callback is not confirmed by the customer side with a “200 OK” response, the system will follow a specific retry strategy.

It is important to also clarify that subscribing for an event and setting a callback for it does not necessarily mean that the callback will occur soon or even at all. We do everything possible to make sure that callbacks have no delays, errors, or issues, and are received as the events occur.

Still, not receiving a callback for a subscribed event for a long time could be due to many reasons. There may be events that need to take days, weeks or months to occur even just once, and some that may encounter problems, errors, issues, and never happen at all.

Callback Retries

When the callback request is sent from Crypto APIs it expects a response from the customer side, as well.

Until a status code “200 OK Request has been successful” is received, Crypto APIs will keep retrying the request. There will be 3 retries in total distributed at certain intervals.

• Crypto APIs will send the requested callback when it’s time and a customer response is expected in the first 5 seconds;
  • If a response isn’t received during that time frame the system is prepared to send in total 3 retries of the callback;
  • The first callback retry will be send after 30 min;
  • After that, each following callback will take twice as long to be sent compared to the previous one. This is done with the purpose to extend the time during which the customer can at all receive the notification and its retries and provide opportunity for the customer to send a “200 OK” response;
  • Additionally, there’s an included “random value” into the algorithm as a factor of ”0.2”, which creates small but important fluctuations in the time frames between callback retries. This ensures that when large volumes of callbacks are sent they would not be in bulk due to having the same time frames, which could otherwise lead to crashes and server issues.

Callback Security

Crypto APIs has incorporated a security layer to keep callbacks from being intercepted, duplicated and make sure customers are receiving their callbacks only from Crypto APIs.

Customer’s Secret Key

The customer’s request can include data on the event they want to subscribe for and has the option to also have a callbackSecretKey. This parameter is an optional security measure for the benefit of the customer. The callbackSecretKey can only be generated by the customer. It is used to create a unique hash string in the x-signature response header in the callback request sent from Crypto APIs when the event occurs.

The callbackSecretKey, and thus the x-signature, are set up per event subscription, not per single callback. Hence the customer only needs to set up the callbackSecretKey once when subscribing for an event. They can use a single callbackSecretKey for all subscriptions, or different ones for each subscription. The security is effective enough even with just one common callbackSecretKey.

Callback Signature

In the case a customer has included a callbackSecretKey in their request to Crypto APIs, the callback (Crypto APIs' request to the customer) includes a specific x-signature value which is for verification purposes. It is used by the customer to verify the information they receive is in actuality really coming from Crypto APIs and not a scam.

The x-signature is provided in the header of the callback and represents a unique hash derived from all the information included in the callback about the event (which must be JSON encoded) and the customer’s callbackSecretKey.

For the purpose HMAC_SHA256 is used. It stands for Hash-based message authentication code and along with its cryptographic hash function SHA256 it represents higher security than any other authentication code.

The cryptographic strength of the HMAC depends upon the size of the callbackSecretKey that has been used. The most common attack against HMACs is brute force to uncover that secret key. HMACs are substantially less affected by collisions than their underlying hashing algorithms alone.

When the customer receives the callback request from Crypto APIs, they can first check the x-signature before processing the request. By using their callbackSecretKey, which only they would know, together with the information from the callback they can generate a hash and compare it to the x-signature hash that the Crypto APIs server has returned. They must match which only then would authenticate Crypto APIs as the true sender.

After authentication of the callback, the customer can then proceed to processing it. If the authentication with the x-signature fails, then the customer must ignore it as someone else is sending it.

Example:

HMAC_SHA256 (callbackSecretKey, The quick brown fox jumps over the lazy dog) = f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbg2d1a3cd8

callbackSecretKey - Represents an optional string the customer can send into their request when they create the callback subscription. The quick brown fox jumps over the lazy dog - Represents everything we post in the body of the server side callback request. f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbg2d1a3cd8 - Represents the resulting hash sent in the header (value name: x-signature) of the post request.

Callback data returned for UTXO-based transactions

Calbacks return more specific information in regards to UTXO-based transactions (BTC). This specification applies to the following events:

• New unconfirmed coins transactions;
• New confirmed coins transactions;
• New confirmed coins transactions and each confirmation.

For:

• 1 occurrence of the address in the input - in the callback we send the amount and the type is outgoing;
• 1 occurrence of address in output - in the callback we send the amount and the type is incoming;
• 2+ occurrences of address in inputs - in the callback we send the total calculated amount and the type is outgoing;
• 2+ occurrences of address in outputs - in the callback we send the total calculated amount and the type is incoming;
• 1 occurrence of address in input AND 1 occurrence of address in output - in the callback we send the amount in the input and the type is outgoing;
• 2+ occurrences of address in input AND 1 occurrence of address in output - in the callback we send the total calculated amount in the input and the type is outgoing;
• 1 occurrence of address in input AND 2+ occurrences of address in output - in the callback we send the amount in the input and the type is outgoing;
• 2+ occurrences of address in input AND 2+ occurrence of address in output - in the callback we send the total calculated amount in the input and the type is outgoing.