Custom store events

If your online store is not WooCommerce, Shopify, Salla or Zid, it can still send its orders, quote requests and products to your workspace. Your store posts a small signed JSON document each time something changes, and each order becomes a contact, a store order and, when paid, a sale in your reports. This page is the contract for the developer of that store. For WooCommerce, follow WooCommerce instead.

Before you start

• Store connections are available when your plan includes Store connections. Your plan may also limit how many active connections you can have.
• Only owners and administrators can create, turn off and re-key a connection.
• You need at least one pipeline, because quote requests open deals in it.
• Your store must be able to send an HTTPS POST from its server, ideally from a background job.

Create the connection

1. Open Products in the sidebar, then Store connections.
2. Under Connect a store, type a Store name.
3. Set Store platform to Our store platform or custom.
4. Choose the stage under New quote requests start in, and optionally a person under Assign new deals to.
5. Leave Webhook key from Shopify or Salla empty.
6. Select Connect a store.
7. Copy the Signing secret. It is shown only once.
8. Copy the Address for your store from the connection's card.

Store both values in your store's environment settings, not in its code:

STORE_EVENTS_URL=STORE_ADDRESS
STORE_EVENTS_SECRET=YOUR_STORE_SECRET

The request

Send each event as a POST to the connection's address, with the JSON document as the body and two headers:

The timestamp must be within 5 minutes of the server's clock, so keep your store's clock synchronised. The signature is checked against the raw bytes you send, so sign the same string you put in the body.

BODY='{"event":"order.created","order":{"id":"1001","number":"1001","status":"pending","currency":"SAR","total":"1250.50","placed_at":"2026-11-06T10:00:00Z","customer":{"name":"Ali Hassan","email":"ali@example.com"}}}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "YOUR_STORE_SECRET" | sed 's/^.* //')

curl -X POST "STORE_ADDRESS" \
  -H "Content-Type: application/json" \
  -H "X-CRM-Timestamp: $TS" \
  -H "X-CRM-Signature: sha256=$SIG" \
  --data "$BODY"

Events

Any other event is refused with 422.

The order document

{
  "event": "order.updated",
  "order": {
    "id": "1001",
    "number": "SO-1001",
    "status": "paid",
    "currency": "SAR",
    "total": "1250.50",
    "placed_at": "2026-11-06T10:00:00Z",
    "updated_at": "2026-11-06T10:05:00Z",
    "customer": {
      "name": "Ali Hassan",
      "email": "ali@example.com",
      "phone": "+966500000002",
      "company": "Hassan Cafe"
    },
    "items": [
      {"sku": "ESP-1", "name": "Espresso machine", "quantity": 1, "total": "1250.50"}
    ],
    "attribution": {
      "source": "google",
      "medium": "cpc",
      "campaign": "ramadan-sale"
    }
  }
}

Capture the campaign tags (utm_source, utm_medium, utm_campaign) when the visitor arrives and save them with the order, so attribution can carry them.

Statuses

How an order is applied

• Newer wins. An event whose updated_at is older than the one already stored is ignored. One with the same updated_at, status and total is ignored as a repeat. Send a fresh updated_at with every change.
• The customer is matched, never overwritten. An email matches an existing active contact first. A phone matches only a contact with no other email, so a shared phone does not join two people. With no match, a new contact is created as a lead from the website, owned by the person chosen under Assign new deals to, and that fires A new lead arrives.
• The customer is fixed by the first event. Later events for the same order ID keep the same contact.
• Every event is safe to repeat. Resending the same document changes nothing.

The quote document

quote.requested uses the same fields as an order, under the key quote. It creates one deal titled with the quote number and the customer's name, in the stage chosen for the connection, with one line for each item. The deal amount is the sum of the item totals, or total when there are no items. A second event with the same quote id is ignored.

The product document

{
  "event": "product.upserted",
  "product": {
    "id": "P-77",
    "name": "Espresso machine",
    "sku": "ESP-1",
    "price": "1250.50",
    "currency": "SAR",
    "active": true,
    "updated_at": "2026-11-06T09:00:00Z"
  }
}

A product is found by its id, or else by its sku, so a product typed in by hand earlier is linked rather than duplicated.

Responses

Sending from your store

Send from a queued job after the order is saved, so a slow or unavailable connection never delays the purchase. Retry on 5xx, 429 and connection errors with a growing pause. Do not retry 403 without fixing the clock or the secret, and do not resend a 422 unchanged.

final class StoreEvents
{
    public function send(string $event, string $key, array $document): void
    {
        $body = json_encode(['event' => $event, $key => $document], JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
        $time = (string) time();
        $signature = 'sha256=' . hash_hmac('sha256', $time . '.' . $body, getenv('STORE_EVENTS_SECRET'));

        $curl = curl_init(getenv('STORE_EVENTS_URL'));
        curl_setopt_array($curl, [
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => $body,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 5,
            CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-CRM-Timestamp: ' . $time, 'X-CRM-Signature: ' . $signature],
        ]);
        curl_exec($curl);
        $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
        curl_close($curl);

        if ($status === 0 || $status === 429 || $status >= 500) {
            throw new RuntimeException('Store event not delivered, retry later.');
        }
    }
}

Test the connection

1. Send an order.created with a test customer and a pending status.
2. Check that the connection's card shows Last event with the time, and that the customer appears in Contacts with the order.
3. Send order.updated with "status": "paid" and a later updated_at. The order should now count as a sale.
4. Send order.updated with "status": "cancelled" and a later updated_at. The order should leave the sales figures.

Good to know

• Past orders are not imported for custom stores. Only events you send from now on arrive.
• Replace the secret makes a new secret at once. Events signed with the old one are refused with 403 from that moment, so update your store straight away and resend anything refused in between.
• Turn off stops the connection: events answer 404 until it is turned on again.
• An erased customer stays erased. Later events for their orders keep the totals right but bring no personal data back.

Troubleshooting