Process Messages

Process messsages are an advanced capability for a connector to make SyncHive call the connector back. These call backs are stored in a persisted queue, with retry and dead lettering capabilties. These can be used for inbound events where the application producing the event doesn't have a suitable retry policy. E.g. Only gives a short time to process an event before timing out. E.g. Has no retry functionality.

Process messages can be complex and technical, so the SyncHive platform has made an effort not to burden end users with the knowledge of process messages. Keep this in mind when providing end user logs.

Event Queueing

To use process messages for queueing inbound events, the connector needs to make an HTTP request to the platform, and be able to handle an HTTP response back from the platform.

Request to SyncHive

The Process request to the platform has the following defintion:

PUThttps://{synchive_url}/v1/process

Example payload

{
  "integrationKey": "SAP",
  "integrationVersion": "1.0",
  "integrationBuildNumber": 1,
  "shapeName": "Product",
  "dataId": "1000",
  "correlationId": "12345",
  "processType": "INBOUND_EVENT"
}

Note the Data ID provided is important, as it is used for sequencing process requests. The platform will not make concurrent callbacks for the same Data ID.

Request from SyncHive

The HTTP request from the platform has the following definition:

PUThttps://{my_connector_url}/v1/process

Example payload (same as above). SyncHive will send the same process message it received from the connector.

{
  "integrationKey": "SAP",
  "integrationVersion": "1.0",
  "integrationBuildNumber": 1,
  "shapeName": "Product",
  "dataId": "1000",
  "correlationId": "12345",
  "processType": "INBOUND_EVENT"
}

Event Queueing Example

Say that we have a Shopify connector where we want to use process messages to queue inbound events. The Shopify connector has been configured with a contact URL of: {my_connector_url}, and integration key of shopify

Whenever the Shopify connector receives a webhook event from Shopify:

{
  "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"
    }
  ]
}

The connector should map the event to a process message and send it to SyncHive:

PUThttps://{synchive_url}/v1/process

{
  "integrationKey": "shopify",
  "integrationVersion": "1.0",
  "integrationBuildNumber": 1,
  "shapeName": "Product",
  "dataId": "632910392",
  "correlationId": "12345",
  "processType": "INBOUND_EVENT"
}

The platform will then call the connector at the following URL: https://{my_connector_url}/v1/process, with the following payload.

PUThttps://{my_connector_url}/v1/process

{
  "integrationKey": "shopify",
  "integrationVersion": "1.0",
  "integrationBuildNumber": 1,
  "shapeName": "Product",
  "dataId": "632910392",
  "correlationId": "12345",
  "processType": "INBOUND_EVENT"
}

The Shopify connector then needs to assemble the product data and publish it to the platform. And respond to the request with an HTTP code of 200.

{
  "dataAction": "CREATE",
  "integrationKey": "shopify",
  "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"
      }
    }
  }
}