How to Integrate Konfiwear Webhooks With Your Custom Cart (Step-by-Step)

What You'll Accomplish

In this tutorial, you'll connect Konfiwear to any platform you control — an OpenCart store, a custom PHP shop, a headless storefront — using Save/API mode. When a shopper finishes designing in the 3D configurator and clicks the CTA button, Konfiwear sends the full design payload to your HTTPS endpoint: preview images, pricing, size breakdown, and production file references. From there, your code takes over — add the item to your cart, create an order, whatever your flow needs.

If you're on Shopify or WooCommerce, you don't need any of this — use the native cart integrations instead. Save/API mode is for everyone else.

Requirements:

• A Konfiwear workspace with access to Save/API mode
• Admin access to your workspace settings
• A publicly reachable HTTPS endpoint that can receive POST requests

By the end, you'll have:

• Save/API mode enabled with your webhook URL configured and tested
• Signature verification protecting your endpoint from forged requests
• Your own session context flowing from your page, through the customizer iframe, back to your server

Step 1 — Enable Save/API Mode

1. In Konfiwear, open your team workspace.
2. Go to Settings → Global → Call to Action.
3. Under Action mode, select Save / API.
4. In the Webhook URL field, enter your HTTPS endpoint (for example, https://shop.example.com/konfiwear/webhook).
5. Click Send test — Konfiwear posts a sample payload to your endpoint and shows you the HTTP status and response time.
6. Click Save Changes.

Two delivery rules to remember: your endpoint must respond with a 2xx status within 10 seconds (anything else shows the shopper an error), and the URL must be HTTPS — localhost and private addresses are not accepted.

Step 2 — Understand the Payload

When a shopper submits a design, your endpoint receives a design.saved.v3 event:

{
  "event": "design.saved.v3",
  "transaction_id": "order-draft-8841",
  "session": {
    "id": "uuid",
    "passthrough": { "s": "your-echoed-value" }
  },
  "products": [
    {
      "product": { "code": "jersey", "name": "Jersey" },
      "quote": { "quote_id": "uuid", "quote_number": "QR-1001" },
      "design": { "size_breakdown": { "m": 2, "l": 1 } },
      "pricing": { "unit_price": 42.63, "total": 127.89, "currency": "EUR" },
      "assets": {
        "previews": [{ "status": "ready", "url": "https://..." }],
        "techpack": { "status": "pending", "url": null }
      }
    }
  ]
}

Here's a real delivery inspected in a webhook debugger — note the X-Konfiwear-Event and X-Konfiwear-Signature request headers alongside the JSON body:

The fields most integrations care about:

• transaction_id — a reference you put on the customizer URL, echoed back to you (Step 4).
• session.passthrough — extra values you configured for echo, also from the URL (Step 4). Only present when configured.
• quote_id — the unique ID of this submission. Use it to deduplicate.
• assets — preview images plus production files. Techpacks and print files are generated in the background; they arrive as "pending" first, and a follow-up design.assets.ready event hits the same URL when each file is ready.

Step 3 — Verify Signatures (Recommended)

Before trusting anything in a webhook body, confirm the request actually came from Konfiwear.

Generate your secret: in Settings → Global → Call to Action → Webhook signing, click Generate secret and copy it immediately — it's shown exactly once. Store it in an environment variable, never in your code or repository. If it ever leaks, regenerate it and update your environment.

With a secret configured, every delivery carries an X-Konfiwear-Signature header — an HMAC-SHA256 of the request body. Verify it like this:

$rawBody = file_get_contents('php://input');
$secret  = getenv('KONFIWEAR_WEBHOOK_SECRET');

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$provided = $_SERVER['HTTP_X_KONFIWEAR_SIGNATURE'] ?? '';

if (!hash_equals($expected, $provided)) {
    http_response_code(401);
    exit;
}

$payload = json_decode($rawBody, true); // safe to process

import { createHmac, timingSafeEqual } from 'node:crypto';

function isValidSignature(rawBody, header, secret) {
  const expected =
    'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');

  return (
    header?.length === expected.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(header))
  );
}

The one common pitfall: always verify against the raw request body. If your framework parses the JSON first and you re-stringify it, the digest won't match.

Step 4 — Embed the Customizer and Pass Your Own Context

Most Save/API integrations embed the customizer in an iframe. The challenge: when the webhook arrives at your server, how do you know which of your shoppers it belongs to? You can't rely on your session cookie — browsers block third-party cookies inside iframes. Instead, pass your context through the URL and let Konfiwear echo it back.

The simple case: transaction_id

Append a reference of your choosing to the URL you load in the iframe:

https://your-domain/c/your-team/jersey?transaction_id=order-draft-8841

Konfiwear echoes it back verbatim in every webhook for that session. Generate it server-side, store it against the shopper's session, and you have a reliable join key.

Custom params: session passthrough

If your platform already produces a session token under its own parameter name (say, s):

1. In Settings → Global → Call to Action, add the param name to Session passthrough params.
2. Append it to your iframe URL: ...?s=7a6f2ca2f15d3a691aaac9ecbc
3. Read it back from the webhook at session.passthrough.s.

Only param names on your configured allow-list are echoed — anything else on the URL is ignored. The names design, quote, rev, saved, and transaction_id are reserved.

Konfiwear also posts a browser message to your parent page when a submission succeeds (konfiwear:design.saved), so your frontend can react instantly — show a confirmation, redirect to the cart — without polling your server.

Step 5 — Handle the Webhook Safely

Standard webhook hygiene applies to Konfiwear the same way it applies to Stripe or Shopify:

1. Verify the signature first. Your webhook URL is reachable from the public internet; the signature is the lock. Reject anything that fails.
2. Treat echoed values as lookup keys, not authentication. transaction_id and session.passthrough come from a URL in a shopper's browser. Use them to find the matching session in your own store, and confirm that session is one you issued and is still active — before adding anything to a live cart.
3. Re-validate pricing against your own catalog before charging anyone, the same way you'd re-check any inbound order data before it hits a payment flow.
4. Deduplicate on quote_id so a retried delivery doesn't create a double order.
5. Acknowledge fast, process async. You have 10 seconds to return 2xx — persist the payload, respond 200, and do the heavy lifting (downloads, cart mutations, ERP calls) in a background job.

Put together, a robust handler looks like:

receive POST
  → verify signature over raw body          (reject if invalid)
  → dedupe on quote_id                      (return 200 if already seen)
  → look up passthrough token in own store  (ignore if unknown)
  → persist payload, enqueue background job
  → return 200
background job
  → re-validate price against own catalog
  → add item to cart / create order

Troubleshooting

Ready to Build?

Save/API mode turns Konfiwear into a design front-end for whatever commerce stack you run. Enable it in Settings → Global → Call to Action, wire up signature verification, and your platform receives every configured design with pricing, previews, and production files attached.

Start your free trial and connect Konfiwear to your platform today.