Skip to main content

Sending Messages to SyncHive

In this guide, we'll cover over the basics of building a Connector to send messages to SyncHive. We'll use an example where we receive a product webhook event from Shopify, transform its contents into a Message, and send it to SyncHive.

1. Creating your API​

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).

Authenticating your requests​

Next, let's set up authentication to securely communicate with SyncHive in the upcoming steps. For this guide, we'll use an HTTP API key.

Include an HTTP API key and value in the request header when you communicate with SyncHive, like so:

Headers
"X-Shopify-Connector-Key": "9XnZr4JmPWTVHuyFBheg"

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. We'll request this information using the x-shopify-shop-domain we received from the webhook.

To do this, we'll make an API call to the following SyncHive endpoint:

GEThttps://{synchive_url}/v1/integration
Headers
"X-Shopify-Connector-Key": "9XnZr4JmPWTVHuyFBheg",
"tenantId": "myshopifystore",
"limber-connector": "shopify_connector",
"Content-Type": "application/json"

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.00,
            "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.

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.