Receiving Messages from SyncHive

In this guide, we'll show you how to set up your Connector to receive messages from SyncHive. We'll use an example where we receive a Product message from SyncHive and save it to Shopify.

1. Creating your API

To receive messages from SyncHive, create an API endpoint for your Connector as follows:

PUThttps://{my_connector_url}/v1/data

2. Receiving data

SyncHive will call your Connector's data endpoint with a message in the payload. This message contains the data that we'll be saving to Shopify.

3. Data transformation

Next, transform the message into Shopify Product data. Here’s an example of the transformation:

Example message:

{
  "dataAction": "UPDATE",
  "integrationKey": "shopify_nz_integration",
  "schemaName": "limber",
  "schemaVersion": "2.1.0",
  "shapeName": "Product",
  "storeKey": "limber",
  "mode": "LIVE",
  "dataId": {
    "@type": "DataReference",
    "schemaName": "limber",
    "shapeName": "Product",
    "externalIdentities": [
      {
        "integrationKey": "shopify_nz_integration",
        "externalId": "632910392"
      }
    ],
    "label": "632910392"
  },
  "data": {
    "@type": "Product",
    "name": "Toaster",
    "sku": "8082STAINLESS",
    "description": "Stainless steel fource slice toaster",
    "externalIdentity": [
      {
        "@type": "ExternalID",
        "internalType": "Product",
        "externalSystemCode": "shopify_nz_integration",
        "externalId": "632910392"
      }
    ],
    "price": {
      "@type": "Monetary",
      "decimalValue": 100.0,
      "currency": {
        "@type": "DataReference",
        "schemaName": "limber",
        "shapeName": "CurrencyUnit",
        "iri": "https://schema.limbergraph.com/limber/CurrencyUnit#NZD",
        "keys": [
          {
            "code": "NZD"
          }
        ],
        "label": "NZD"
      }
    }
  }
}

Example transformed data:

{
  "title": "Toaster",
  "body_html": "<p>Four slice toaster.</p>",
  "status": "active",
  "variants": [
    {
      "product_id": 632910392,
      "title": "Stainless Steel",
      "price": "100.00",
      "sku": "8082STAINLESS"
    }
  ]
}

4. Sending data to Shopify

Once you've transformed the data, the next step is to send it to Shopify. But before we can do that, we need to get the details of the specific Shopify store where the product will be sent. To do this, we'll extract the required information from the message:

integrationKey
integrationVersion
integrationBuildNumber

Then, use this information to request the Shopify integration details from SyncHive:

POSThttps://{synchive_url}/v1/integration/{integrationKey}/{integrationVersion}/{integrationBuildNumber}

Headers
"X-Shopify-Connector-Key": "9XnZr4JmPWTVHuyFBheg",
"limber-connector": "shopify_connector",
"Content-Type": "application/json"

This will return the following information about the Shopify NZ instance:

httpUrl: https://www.my_shopify_url.com
httpApiKeyHeader: X-Shopify-Access-Token
httpApiKeyValue: 3tuCsUi3zopbxWmuqFDe

Use this information to send your Shopify product data to the Shopify NZ instance:

POSThttps://www.my_shopify_url.com/admin/api/2024-1/products.json

Headers
"X-Shopify-Access-Token": "3tuCsUi3zopbxWmuqFDe",
"Content-Type": "application/json"

Body

Your Shopify Product

5. Responding to SyncHive

After sending the product data to Shopify, we need to respond to SyncHive for two reasons: to inform SyncHive of our success or failure, and to determine if we need to link the Shopify NZ instance to this data in SyncHive.

Linking identities

First, let's discuss linking data in SyncHive.

When you link instances to data in SyncHive, you're telling SyncHive which data is used by which external systems.

When to link identities

If the message you received from SyncHive has an empty externalIdentities array, this means that Shopify NZ does not have this product data. In this case, we need to link the Shopify NZ instance to this data in SyncHive.

Example payload:

{
    "dataAction": "CREATE",
    "integrationKey": "shopify_nz_integration",
    "schemaName": "limber",
    "schemaVersion": "2.1.0",
    "shapeName": "Product",
    "storeKey": "limber",
    "mode": "LIVE",
    "dataId": {
        "@type": "DataReference",
        "schemaName": "limber",
        "shapeName": "Product",
        "externalIdentities": [], <--- Empty
        "label": "632910392"
    },
    "data": {
        "@type": "Product",
        "name": "Toaster",
        "sku": "8082STAINLESS",
        "description": "Stainless steel fource slice toaster",
        "externalIdentity": [], <--- Also empty
        "price": {
           ...
        }
    }
}

Conversely, if the message you received from SyncHive has values in the externalIdentities array, this means that Shopify NZ does have this product data, and you can skip this step.

Example payload:

{
    "dataAction": "UPDATE",
    "integrationKey": "shopify_nz_integration",
    "schemaName": "limber",
    "schemaVersion": "2.1.0",
    "shapeName": "Product",
    "storeKey": "limber",
    "mode": "LIVE",
    "dataId": {
        "@type": "DataReference",
        "schemaName": "limber",
        "shapeName": "Product",
        "externalIdentities": [ <--- Not empty
            {
                "integrationKey": "shopify_nz_integration",
                "externalId": "632910392"
            }
        ],
        "label": "632910392"
    },
    "data": {
        "@type": "Product",
        "name": "Toaster",
        "sku": "8082STAINLESS",
        "description": "Stainless steel fource slice toaster",
        "externalIdentity": [ <--- Also not empty
            {
                "@type": "ExternalID",
                "internalType": "Product",
                "externalSystemCode": "shopify_nz_integration",
                "externalId": "632910392"
            }
        ],
        "price": {
            ...
        }
    }
}

How to link an identity

To link the data contained in this message to the Shopify NZ instance, use the following payload when responding to SyncHive:

{
  "externalIdentity": {
    "integrationKey": "shopify_nz_integration",
    "externalId": "632910392" <--- The Shopify product ID
  },
  "linkIdentities": {
    "integrationKey": "shopify_nz_integration",
    "linkIdentities": [
      {
        "iri": "https://schema.limbergraph.com/limber/Product#632910392",
        "externalId": "632910392"
      }
    ]
  },
  "publishStatus": "SUCCESS"
}

If you do not need to link the data contained in this message to the Shopify NZ instance, simply respond with an empty body.

A note on asynchronous identity linking

For asynchronous scenarios, use "publishStatus": "ACCEPTED" instead of "publishStatus": "SUCCESS". This informs SyncHive that further processing of this data is required before it is considered successful.

At the point that further processing of this data has been completed and this data is considered to be successful, please use linkIdentities in the Event Log API. Refer to Event Logging: Asynchronous Processing for more information.

Providing a response code

After deciding whether to link this data to the Shopify NZ instance, we also need to inform SyncHive of our success or failure. Provide a 200 HTTP response code to indicate success, or any non-200 code along with a reason for the failure in the message body.

1. Creating your API​

2. Receiving data​

3. Data transformation​

4. Sending data to Shopify​

5. Responding to SyncHive​

Linking identities​

When to link identities​

How to link an identity​

A note on asynchronous identity linking​

Providing a response code​