Callbacks¶

Callbacks allow you to receive notifications whenever the state on an object changes (or something important happens to that object).

To set up Callbacks for an object, set a callback_url on that object. Whenever something important happens to the object that we think you should be notified of (typically a state change), we will make an HTTP POST request to your callback_url with the object_id in the body of the request.

Configure Callbacks¶

To configure your callbacks, go to Commerce Settings > Integration > Callbacks and add a callback URL.

Callback Requests¶

The HTTP request that we make to your callback_url will have the following characteristics:

• It will be a POST request.
• Request Body will be in JSON-API format. It is the same as in public API.
• The object type and id will be in the body of the request (and not added as a url-parameter).

This an example for Payout Invoice operation callback data:

{
   "data":{
      "type":"payment-invoices",
      "id":"cpi_UoIW6RdSYyIRj8vR",
      "attributes":{
         "status":"process_pending",
         "resolution":"ok",
         "moderation_required":false,
         "amount":4,
         "payment_amount":4,
         "currency":"UAH",
         "service_currency":"UAH",
         "reference_id":"e2041fe2-44da-44da-0090-4ffe9d2f25d0",
         "test_mode":false,
         "fee":0,
         "deposit":4,
         "processed":null,
         "processed_amount":null,
         "processed_fee":null,
         "processed_deposit":null,
         "metadata":[

         ],
         "flow_data":{
            "action":"https://cardgate.example.io/hpp/2018e26d-8882-57f6-9a91-ac2acfeedbe3",
            "method":"GET",
            "params":[

            ]
         },
         "flow":"hpp",
         "created":1560889898,
         "updated":1560889898,
         "payload":[

         ]
      },
      "relationships":{
         "payment-service":{
            "data":{
               "type":"payment-services",
               "id":"payment_card_uah_hpp"
            }
         },
         "payment-method":{
            "data":{
               "type":"payment-methods",
               "id":"payment_card"
            }
         }
      },
      "links":{
         "self":"/api/payment-invoices/cpi_UoIW6RdSYyIRj8vR"
      }
   }
}

You also have the option to exclude card object from the callback. Enabling this will remove the masked card details object from the callback.

API Version¶

Corefy supports multiple API versions. The event content sent to the callback is structured based on the API version selected. Hence it is crucial that the API version of the callback matches the API version of the client library used by your application server. Learn more about API versioning here.

Signature¶

Corefy sign data using secret keys. They can be obtained in organization or Commerce Account settings. All callbacks are signed live or test secret key according to the mode in which operation has been created.

Corefy sends signature in X-Signature callback request header. The signature is created by next algorithm:

$signature = base64_encode(sha1($secret . $callbackData . $secret, true));

Where the $secret is one your secrets: test or live, $callbackData is raw json data.

Timeouts¶

There are 3 timeouts for Callbacks in Corefy:

1. Connection Timeout: The connection timeout is the timeout for making the initial connection to the callback URL's HTTP server.
2. Read Timeout: Once the initial connection has been made, at any time there is a possibility that there is an indefinite wait to read data from the HTTP server. The read timeout is the timeout for such a wait.
3. Total Callback Timeout: In addition to the above timeouts, Corefy also checks the total execution of time of any callback via the callback execution timeout.

The values for each timeout are as follows:

Automatic Retries¶

When you successfully process callback request, you must return 200 HTTP status code. Our application ignores any other data return by callback.

If the callback returns status code other then 200, it is assumed the delivery of request failed. The failed callback request is resent with an increasing delay between each attempt:

• the 1^st retry 1 minute after the initial attempt,
• the 2^nd retry 2 minutes after the 1^st retry,
• the 3^rd retry 3 minutes after the 2^nd retry,
• the 4^th retry 4 minutes after the 3^rd retry,
• the 5^th retry 5 minutes after the 4^th retry,
• the 6^th retry 6 minutes after the 5^th retry,
• and so on, up to 100 attempts or up to receiving 200 HTTP status code.

You can set up delays between Callbacks' requests and the number of attempts in the Commerce settings.

Additionally, you can avoid receiving unnecessary messages in Callbacks by toggling the "Only final" statuses option.

Callback Handling¶

Because HTTPS/SSL verifies the identity of the server you are making API calls to, you will always know that the updated information you are receiving is correct.

If we sent object information in the Callback itself, you would have to verify the authenticity of the information via signed request, etc.

Duplicate Handling¶

Due to callback retries, it's possible that your application receives the same callback more than once. Ensure idempotency of the callback by detecting such duplicates within your application.

To control processing idempotency use by examining the id parameter in callback request data since its value is unique to an operation and thus identifies it.

For some applications, this is not a serious issue. Work that can be repeated without changing the outcome is called idempotent. If your app's actions are always idempotent, you don't need to worry much about concurrency.

Batching¶

We will batch Callbacks for the same object that are very close together. So if a payment goes from state created to invoked to processed immediately, you will only receive one Callback and when you look up the status of the payment it will be processed.

The advantage of doing this is that it prevents us from overwhelming your server(s) with HTTP requests and it prevents your app from having to build complicated logic around sequential state changes. Your app should only care about the latest state the object is in.

Out-of-Order Delivery¶

Callbacks can also arrive at your application out-of-order. This can be due to issues such as network delays or callback failures. However, you can determine the order of the events by examining the updated attribute of the resource sent by the callback. updated is timestamp value that updated for every change made to the resource.

IPs whitelist¶

We use Amazon's EC2 for our infrastructure and currently we do not have a static IP address assigned. IP addresses for our instances are automatically allocated by Amazon, as we scale up or down. Hence, we are unable to provide any specific IP address for whitelisting.