Return to site

Sending Data

Simply send data, live events and batch

Our objective is to make sending us data as simple as possible. You don’t need to play around with authorizations or have any structure to your data imposed by linked2. However, it is advisable to follow standard webhook procedures so that even without authorization we can still verify that the data we receive came from who it claims to have come from.

You can send data via live webhook events or in batches with whatever frequency you want. The Linked2 platform can process batches of thousands of orders in seconds and can handle hundreds of webhook requests per second.

If you need a connector from your system to Linked2 we can also help with that. We can deploy data collection agents that run locally or can be hosted in our cloud to run against a schedule or can be triggered remotely. A use case for this kind of data collection agent is to pull data from a database or API against a constant query, such as all data for the last week, the last day, or to process things like fresh orders or new customers. Another good use case for this kind of data collection agent is for refreshing and updating data for analytics.

At Linked2 we recognize the most basic thing you need to do is send data. We make this equally simple for webhook events and API batch process.

Definitions of webhooks and APIs are blurred at best but at Linked2 we think a webhook is best described as a way of reacting to an event. Examples of events are a new order created or a customer updated. A webhook provides a method of informing another system of that event occurrence. If you want a live integration then webhooks are the way to go. A webhook always sends data and needs a webhook receiver. They are simple to use, require minimal authorisation because they are only sending data, never fetching, and are triggered automatically when an event happens.

An typically API covers a wider spectrum including endpoints for fetching, creating, updating, and more. Usually an authorization process is required before access is granted or even per request. Compared to a webhook that pushes events an API is more about pulling data or issuing commands.

Webhook Live Event Data

For us to accept webhook live event data we need two elements in play – your software must be able to trigger a webhook and the Linked2 platform must have a webhook receiver for your trigger. We have two types of receiver; a generic receiver which is ready to go but you must conform to and platform specific webhook receivers which we must deploy to accept data from you. Both require some request header information and a JSON body payload.

We use the headers to verify that the webhook has actually come from who it claims to have come from.

Generic Linked2 Receiver

The generic receiver is simple and is fast to get going with because we at Linked2 do not need to do any work to start receiving your data.

On the other hand, you need to be able to configure your webhook to have the expected HTTP headers and use the same SHA-256 HMAC (hash message authentication code). If you already have established webhooks then probably your best option is to ask us to deploy a receiver specific to your webhook.

Our generic webhook receiver expects the following headers in the HTTP request:

· X-Linked2-Hmac-Sha256

· X-Linked2-Host

· X-Linked2-Topic

The X-Linked2-Hmac-Sha256 header must contain a base64 encoded SHA-256 hash of the body of your webhook. The SHA-256 hash must be calculated with the shared secret that was given during the on-boarding process.
 

The X-Linked2-Host header is an identifier for the user of the integration. If you are a platform that hosts other businesses, then your end-customer is the host. The host header can be in the form of a URL or anything, just it should be unique to your end-customer.

The X-Linked2-Topic header is about naming the event that caused the webhook trigger to fire. Good examples of this are:

· Order/Create

· Order/Update

· Customer/Create

· Customer/Update

· Product/Delete

So that’s all we need in the headers… what about the body of the request?

Well, so long as the body is valid JSON it can literally have whatever structure is best for you. The receiver only cares that it receives valid JSON. It will validate the JSON it receives against your integration requirements, including header content like the SHA-256 HMAC, and either accept or reject the webhook request based on that validation.

Having said that we recommend you structure your JSON like this:

{
"me
ta" :{ },
"
data": { }
}

Place your JSON data inside the data property using any schema/structure you like and use the meta object to send some properties that are meaningful to you, such as your customer identifier, the type of object you are sending, etc. If you choose to use the 'meta' object (it is up to you) then it has special meaning for us. Any information passed within the 'meta' object will be preserved throughout the integration process and it will be included in notifications given to you and your customers.

Platform Specific Webhooks

The Linked2 platform uses a webhook framework to make rapid webhook receiver deployment a simple task. If you already have established your webhooks and have your headers in place, or have specific security requirements, or otherwise do not wish to add to or change your webhook events, then just lets us know. We will deploy a receiver specifically for your platform. We already have several platform specific receivers operational and they typically take less than a day for us to deploy assuming standard webhook procedures, such as SHA-256 HMAC, etc.

Batch API

Batch still has an important part to play in systems integration and Linked2 can accept batch data in JSON and for legacy reasons we also support CSV. We strongly recommend JSON over CSV because JSON can contain information about data relationships and is much better suited to systems integration than CSV.

The Batch API has been designed to be as simple as possible and again there is very little requirement on data structure.

Batches can be any size and they maybe intelligently chunked into smaller pieces depending on the requirements of the target system. For example, you may send data by batch, but your target system may not be able to accept batches. Linked2 can handle this for you and intelligently slice your batch into separate API calls without exceeding the limitations of the target API.

We treat a batch request in a similar manner to the generic webhook and first require some HTTP headers to be set.

·X-Linked2Batch-Signature

·X-Linked2Batch-Hmac-Sha256

Because of batch sizes we don’t require a whole message hash to be calculated. Instead give us a signature in the header and calculate the SHA-256 hash based on this and place the base64 encoded SHA-256 in the X- Linked2Batch-Hmac-Sha256 header.

A typical signature could be something like your system name, the batch name and the date-time concatenated into a single set of bytes. We will calculate the SHA-256 from the given signature based on our shared secret and test for a match.

Upload the batch to our JSON batch end-point at https://platform.linked2.io/batch/json/{your-stageId} using multi-part form file.

Similar to webhooks we expect the file content should have the following JSON structure:

{

“meta”: {},

“data”: []

}

The meta property is optional but if you wish to populate it then we will preserve that information throughout the integration process and whenever we report on an integration you meta data will be included in that report. You can use this to help you track down the source of any integration issues and such information can be very useful in supporting end-customers.

The data property is expected to be an array of any arbitrary JSON objects, but they must conform to the same object schema. An array of customers, an array of orders, etc.

The next Linked2 release will be able to accept data of varying object schemas in the same batch, so you will be able to send multiple arrays of data such as a list or orders, a list of customers and a list of products all in a single batch file.

All Posts
×

Almost done…

We just sent you an email. Please click the link in the email to confirm your subscription!

OK