Skip to main content

Sending Messages to SyncHive

In this guide, we'll be following from our previous guide on setting up a Connector and Integration, by walking through what needs to be implemented to be able to send messages to SyncHive. We'll use the same example where we receive a product webhook event from Shopify, transform its contents into a message, and send it to SyncHive.

1. Setup your Webhook API endpoint​

To start, create an API endpoint for your Connector to receive webhooks from Shopify. Use a structure like the example below.

POSThttps://{my_connector_url}/webhook/product

Configuring Shopify​

Configure Shopify to call your API for product create, update, and delete webhook(s).

Detailed instructions on configuring Shopify webhooks are not included in this guide.

2. Receiving a webhook and creating a message​

After receiving a webhook from Shopify, we'll examine its contents:

Headers
"x-shopify-shop-domain": "myshopifystore"
{
  "id": 632910392,
  "title": "Toaster",
  "body_html": "<p>Four slice toaster.</p>",
  "created_at": "2024-01-02T08:59:11-05:00",
  "updated_at": "2024-01-02T08:59:11-05:00",
  "status": "active",
  "variants": [
    {
      "id": 808950810,
      "product_id": 632910392,
      "title": "Stainless Steel",
      "price": "100.00",
      "sku": "8082STAINLESS"
    }
  ]
}

We'll convert this data into a message that follows SyncHive's Schema. All data sent to SyncHive must be in this message format, conforming to SyncHive's Schema. For this example, we're using the Product Schema.

Before creating the message, we'll need more details from SyncHive. To make the request we'll need to send the following values as headers:

  • X-Shopify-Connector-Key: The API Key Value registered against the Connector. More info.
  • limber-connector: The Connector Key setup against the Connector. More info.
  • Content-Type: application/json (since we're expecting to receive JSON data).

And the following as query parameters:

  • tenantId: The Tenant ID setup against the Integration. More info.

Now to request for more details, we'll make an API call to the following SyncHive endpoint:

GEThttps://{synchive_url}/data-service/v1/integration?tenantId={my_tenant_id}
Headers
"X-Shopify-Connector-Key": "9XnZr4JmPWTVHuyFBheg",
"limber-connector": "shopify_connector",
"Content-Type": "application/json"
Query parameters
"tenantId": "myshopifystore"
Response
{
  "schemaName": "limber",
  "schemaVersion": "2.1.0",
  "integrationKey": "shopify_nz_integration"
  //...
}

Now, with the integrationKey, schemaName, and schemaVersion we received from SyncHive, let's create our message. The shapeName categorizes the data we're sending, and in this case, we're using Product.

Here's an example of the webhook data transformed into a message:

{
  "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": [
      {
        "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"
      }
    }
  }
}

3. Sending a message to SyncHive​

Send the message to SyncHive using the data endpoint.

Example API call:

PUThttps://{synchive_url}/data-service/v1/data
Headers
"X-Shopify-Connector-Key": "9XnZr4JmPWTVHuyFBheg",
"limber-connector": "shopify_connector",
"Content-Type": "application/json"
Body
Message

(See message example above)

Handling responses​

Handle both successful and unsuccessful message deliveries. SyncHive will respond with a 200 status for successful deliveries and a non-200 status with an explanation for failures. See more.

4. Validating a message in SyncHive​

You can view your message in SyncHive by navigating to the "Data" page and searching for your data, such as by SKU for Product data.

Next steps: Receiving messages from SyncHive​

This guide covered the basics of sending messages to SyncHive. In the next guide, we'll cover receiving messages from SyncHive.