Technical Details

This article covers the integration architecture, data flows, and processing behavior for implementers.

​

Architecture overview

The connector runs as an ASP.NET Core application on AWS Lambda. Incoming BigCommerce webhooks are validated synchronously for signature integrity, then handed off asynchronously via SQS. A separate Lambda function polls the SQS queue and processes events in parallel batches.

​

Webhook authentication

Every incoming webhook from BigCommerce is verified before processing:

1. The connector extracts the store hash from the producer field of the payload.
2. It looks up the client secret for that store from the secrets store.
3. It computes an HMAC-SHA256 digest of the raw request body using the client secret.
4. The result is compared against the X-BC-Signature request header.

If the signature doesn’t match, the request is rejected with 401 Unauthorized. If validation passes, the payload is queued for asynchronous processing.

​

Contact sync

​

Real-time webhook flow

The following BigCommerce webhook scopes trigger contact upserts in Engage: When a created or updated event arrives, the connector:

1. Fetches full customer data from BigCommerce v3 (customers?id:in={id}&include=addresses).
2. Extracts the origin_channel_id to resolve which sales channel the customer belongs to.
3. Checks whether a contact with that email already exists in Engage.
4. Creates a new contact or updates the existing one.

​

Contact field mapping

Phone numbers are validated and normalised to E.164 format using the libphonenumber library. Invalid numbers are omitted rather than stored in a broken format

​

Order sync

​

Webhook events

When store/order/statusUpdated fires for a refund status (status ID 4 or 14), the connector skips it. The authoritative event for refunds is store/order/refund/created.

​

Two-phase processing

1. Stage — When a webhook arrives, the connector fetches order and line item data from BigCommerce and writes a Pending record with the full payload.
2. Process — The event processor picks up pending records and sends the order to Engage.

If processing fails, the event is retried automatically up to 10 times. Records that exhaust all retries are marked as failed.

​

Order status mapping

The following statuses are skipped — no action is taken in Engage:

• Awaiting Payment (7)
• Awaiting Shipment (9)
• Manual Verification Required (12)
• Declined (6)
• Any unrecognised status ID

​

Line items and promotions

For each order, the connector:

• Maps each line item to a Voyado line item (SKU, quantity, price, discount) using v2/orders/{id}/products.
• Fetches payment methods from BigCommerce and attaches them to the order payload.
• Looks up any coupon code applied to the order and redeems the matching Engage promotion if found.

​

Return orders

When store/order/refund/created fires:

1. The refund_id is extracted from the payload.
2. The connector fetches the parent order data.
3. A pending record is written with the return type and refund_id as a sub-identifier.
4. The event processor processes it as a RETURN order using the status mapping table above.

​

Cart tracking

The storefront posts cart data to the connector. The connector:

1. Resolves the store and channel from hash and saleschannelUrl.
2. Checks that Cart tracking is enabled.
3. Fetches the store locale from BigCommerce (v3/settings/store/locale).
4. Builds a cart payload and posts it to Voyado’s Collect API.

The cart payload includes: cart ID, line items with SKU and quantity, session ID, contact ID, URL, locale, and UTM tags.

​

Cart-converted webhook

When BigCommerce fires store/cart/converted, the connector:

1. Extracts the orderId from the payload.
2. Fetches the order from BigCommerce to get the channel_id and billing_address.email.
3. Looks up the Engage contact ID for that email.
4. Posts a cart event to the Collect API with the resolved contact ID, linking an empty cart session to the identified contact.

​

Product tracking

The storefront posts product view data to the connector. The connector:

1. Resolves the store and channel from hash and saleschannelUrl.
2. Checks that Product tracking is enabled.
3. Fetches the product from BigCommerce by SKU (v3/catalog/products?sku={sku}).
4. Resolves up to 5 category names from the product’s category IDs (most specific categories). Category names are joined with / and capped at 255 characters.
5. Fetches the store locale.
6. Builds a productview payload and posts it to the Collect API.

If the product SKU category is not found in BigCommerce, the category is extracted from the product URL path as a fallback. If the BigCommerce API returns a 5xx error, the connector retries the request up to 3 times before dropping the event.

​

Multi-channel support

A single BigCommerce store can have multiple sales channels, each with its own configuration and site record. The connector resolves the correct configuration by matching store hash and sales channel ID. For webhook scopes that don’t include a channel_id, the connector fetches the customer or order from BigCommerce to discover the channel before routing.

​

Webhook health and self-healing

A background job periodically checks all registered BigCommerce webhooks. It:

• Re-activates inactive webhooks via a PUT to BigCommerce’s v3/hooks/{id}.
• Detects missing webhook scopes and registers them.

This keeps the connector operational after periods of inactivity or after BigCommerce automatically deactivates low-volume webhooks. The job does not replay events missed while a webhook was inactive.