For developers

Connect your own website (API and webhooks)

Connect a website you built yourself through a Products API, an Order API and webhooks — the full guide for its developers.

The video for this guide is coming soon.

Last updated: 16 October 2026

← Help center

1What you need

Your website provides two APIs and sends OmniConva webhooks when products or orders change. Everything is JSON over HTTPS.

PartDirectionRequired?
Products API — the catalog, page by pageOmniConva → websiteYes
Order API — when a customer confirms an order in chatOmniConva → websiteYes
Product Detail API — a live price and stock check before an orderOmniConva → websiteNo
Webhooks — product and order status changesWebsite → OmniConvaStrongly recommended

Two JSON formats are accepted: Standard (for a new integration) and Alternative — a nested structure with metadata, pricing, variations and orders with contact/line_items that many sites already expose. Pick Alternative and your site's code doesn't change, only the URLs and tokens.

2Laravel site? Use the package

For Laravel 12 or 13 (PHP 8.2+), the omniconva/laravel package handles every API and webhook below for you: it verifies our request signatures, never creates an order twice, and sends webhooks when products change. Your developer writes two classes.

composer require omniconva/laravel
php artisan omniconva:install
php artisan migrate
class Products extends EloquentProductSource
{
    public function query(): Builder
    {
        return Product::query()->with(['variants', 'images']);
    }

    public function map(Model $product): ProductData
    {
        return ProductData::make($product->id, $product->name)
            ->url(route('products.show', $product))
            ->price($product->price)
            ->salePrice($product->sale_price)
            ->stockQuantity($product->stock)
            ->images($product->images->pluck('url'))
            ->variants($product->variants->map(
                fn ($v) => VariantData::make($v->id, $v->name)
                    ->price($v->price)
                    ->stockQuantity($v->stock)
                    ->options(['Size' => $v->size])
            ));
    }
}
app/OmniConva/Products.php — which products, and how they map
class Orders implements OrderHandler
{
    public function createOrder(OrderData $order): OrderResult
    {
        $saved = Order::create([
            'customer_name' => $order->customer->name,
            'phone' => $order->customer->phone,
            'address' => $order->shippingAddress->address,
            'total' => $order->total,
        ]);

        return OrderResult::make($saved->id, $saved->number);
    }
}
app/OmniConva/Orders.php — saving an order
  • Add use SyncsWithOmniConva; to the product model and every save or delete updates OmniConva.
  • Report order status with OmniConva::orderUpdated($id, 'shipped', $tracking).
  • Put <x-omniconva-chat /> in your layout to show the chat widget.
  • php artisan omniconva:test checks that everything is wired up.
TipIn the dashboard pick Custom website › Setup method › Laravel package: no URLs or headers to type, only your website address. The rest of this guide is for hand-built APIs.

3Node.js site? Use the package

For sites on Express, NestJS, Next.js, Hono or Bun, the @omniconva/node package does the same: it serves the APIs, verifies signatures, never creates an order twice and sends the webhooks. Your developer writes two functions.

import express from 'express';
import { createOmniConva } from '@omniconva/node';

const omniconva = createOmniConva({
  products: {
    async list({ page, perPage }) {
      const { rows, total } = await db.products.page(page, perPage);
      return { products: rows.map(toOmniConva), total };
    },
    async get(id) {
      const row = await db.products.find(id);
      return row ? toOmniConva(row) : null;
    },
  },
  orders: {
    async create(order) {
      const saved = await db.orders.create(order);
      return { orderId: saved.id, orderNumber: saved.number };
    },
  },
});

const app = express();
app.use(omniconva.express()); // before express.json()

// after saving a product
await omniconva.productUpdated(toOmniConva(product));
npm install @omniconva/node
TipIn the dashboard pick Custom website › Setup method › Node.js package. The package README has the full code.

4Connect in the dashboard

  1. Press Connect on the Custom website row under Connections.
  2. Enter the Website URL, the currency and the API format.
  3. Enter the Products API URL and headers (such as Authorization: Bearer …), then press Test Products API — it shows the first page's products as we read them.
  4. Enter the Order API URL and headers. Optionally send one with Send test order.
  5. Press Connect website. The product import starts on its own, and the Webhooks section shows your webhook URL, token and signing secret.
TipThe Developer guide button shows this guide filled in with your store's own URLs and token — print it or save it as a PDF for your developer.
Good to knowThis needs an active plan and the store owner role. API addresses must be public https URLs.

5Products API (Standard format)

GET https://yourwebsite.com/api/products?page=1&per_page=50
Authorization: Bearer <your products API token>

page starts at 1. Parameter names can be changed, extra query parameters added, and a POST with a JSON body (using {page} and {per_page}) is supported.

{
  "products": [
    {
      "id": "1001",
      "title": "Hero Hoodie",
      "url": "https://yourwebsite.com/products/hero-hoodie",
      "description": "<p>Warm fleece hoodie.</p>",
      "short_description": "Warm fleece hoodie.",
      "status": "active",
      "sku": "HOODIE",
      "brand": "Hero",
      "categories": [
        "Hoodies"
      ],
      "tags": [
        "fleece"
      ],
      "images": [
        "https://cdn.yourwebsite.com/hoodie.jpg"
      ],
      "currency": "BDT",
      "price": "1500.00",
      "sale_price": "1200.00",
      "in_stock": true,
      "stock_quantity": 7,
      "variants": [
        {
          "id": "1001-M",
          "title": "M",
          "sku": "HOODIE-M",
          "price": "1500.00",
          "sale_price": "1200.00",
          "in_stock": true,
          "stock_quantity": 7,
          "image": null,
          "options": {
            "Size": "M"
          }
        }
      ],
      "updated_at": "2026-10-01T10:00:00Z"
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 128,
  "has_more": true
}
Response
FieldNotes
id, titleRequired. An id never changes; variants need their own id.
statusactive is for sale; draft or anything else is not.
price, sale_priceA sale_price only counts when it is below price.
in_stock, stock_quantityEither or both. stock_quantity: null means stock isn't counted.
imagesAbsolute https URLs; up to 8 are kept.
has_moreWhether another page follows. Without it, total decides.

6Product webhooks (website → OmniConva)

POST https://api.omniconva.com/webhooks/custom-website/<store id>
Authorization: Bearer <webhook token>
X-Webhook-Topic: product.updated
Content-Type: application/json
X-Webhook-TopicBody
product.created, product.updatedThe full product, same shape as in the Products API.
product.deleted{"id": "1001"}
order.updatedSee order status below.

In the Alternative format the topics product/create, product/update, product/delete also work, and a delete body may be {"product_id": …}. Answers: 200 applied, 400 unusable body (the message says why), 401 wrong token or signature. Use a timeout of about 5 seconds and retry on 5xx.

Signing webhooks (recommended)

Add X-OmniConva-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256> of "<t>.<raw body>" with the signing secret. Signatures older than 5 minutes are refused. Once every webhook is signed, turn on Require signed webhooks in the dashboard.

// Node.js: sign the exact body you send.
const crypto = require("crypto");
const body = JSON.stringify(payload);
const t = Math.floor(Date.now() / 1000);
const v1 = crypto
  .createHmac("sha256", SIGNING_SECRET)
  .update(`${t}.${body}`)
  .digest("hex");

await fetch(WEBHOOK_URL, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${WEBHOOK_TOKEN}`,
    "X-Webhook-Topic": "product.updated",
    "X-OmniConva-Signature": `t=${t},v1=${v1}`,
  },
  body,
});

Our requests are signed too

Every call OmniConva makes to your APIs carries X-OmniConva-Signature: the HMAC, with the same secret, of "<t>.<METHOD>.<path and query>.<body>" (empty body for a GET). Verify it to be sure a call came from us.

7Order API (Standard format)

POST https://yourwebsite.com/api/orders
Authorization: Bearer <your order API token>
Content-Type: application/json
Idempotency-Key: <OmniConva order id>
{
  "id": "6a3f0c1e-2b7d-4c1a-9f3e-8d2b1c0a9e77",
  "order_number": "1042",
  "source": "omniconva",
  "currency": "BDT",
  "customer": {
    "name": "Rahim Uddin",
    "phone": "01711000000"
  },
  "shipping_address": {
    "address": "House 12, Road 4, Dhanmondi",
    "city": "Dhaka",
    "state": null,
    "postcode": null,
    "country": "BD"
  },
  "items": [
    {
      "product_id": "1001",
      "variant_id": "1001-M",
      "sku": "HOODIE-M",
      "title": "Hero Hoodie – M",
      "quantity": 2,
      "unit_price": "1200.00",
      "total": "2400.00",
      "image": "https://cdn.yourwebsite.com/hoodie.jpg"
    }
  ],
  "subtotal": "2400.00",
  "discount": "0.00",
  "shipping": {
    "title": "Inside Dhaka",
    "amount": "60.00"
  },
  "fees": [],
  "total": "2460.00",
  "payment": {
    "method": "cash_on_delivery",
    "status": "unpaid"
  },
  "note": "Placed through OmniConva chat, cash on delivery."
}
What OmniConva sends
{
  "order_id": "W-5531",
  "order_number": "5531"
}
Your response (any 2xx)
Good to knowA failed push is retried about 6 times within an hour with the same Idempotency-Key. If you've seen the key before, return the first order (2xx, or 409 with its id) instead of creating another.
TipTest orders from the dashboard carry "test": true and an X-OmniConva-Test: 1 header — discard them.

8Product Detail API (optional)

GET https://yourwebsite.com/api/products/{id}

Return one product (same shape as in the Products API), or 404 when it no longer exists. With it, live price and stock are checked before an order is confirmed; without it, the catalog your webhooks keep current is used.

9Order status updates

Same webhook URL and token, with X-Webhook-Topic: order.updated. Use the id your Order API returned (or ours as omniconva_order_id). The AI can then answer "where is my order?", and the dashboard's Orders page shows the status and tracking.

{
  "order_id": "W-5531",
  "status": "shipped",
  "tracking": {
    "number": "TRK123",
    "carrier": "Pathao",
    "url": "https://track.example.com/TRK123"
  },
  "note": "Rider assigned",
  "updated_at": "2026-10-10T10:00:00Z"
}

10Alternative format

Same APIs and webhooks, different JSON. Pick API format › Alternative in the dashboard.

{
  "metadata": {
    "total": 128,
    "page": 1,
    "per_page": 50
  },
  "products": [
    {
      "id": 6001,
      "title": "Classic Cotton T-Shirt",
      "url": "https://yourwebsite.com/products/classic-cotton-tshirt",
      "description": "<p>Premium organic cotton t-shirt.</p>",
      "summary": "Premium organic cotton t-shirt.",
      "published": true,
      "is_draft": false,
      "purchasable": true,
      "sku": "TSHIRT-CLASSIC",
      "brand": "EcoWear",
      "tags": [
        "cotton"
      ],
      "categories": [
        {
          "id": 20,
          "title": "Shirts",
          "slug": "shirts"
        }
      ],
      "images": [
        {
          "url": "https://cdn.yourwebsite.com/tshirt.jpg"
        }
      ],
      "pricing": {
        "regular_price": "24.99",
        "sale_prices": []
      },
      "inventory": {
        "stock_status": true,
        "stocks": []
      },
      "variations": [
        {
          "id": 6002,
          "title": "Small / Red",
          "sku": "TSHIRT-S-RED",
          "published": true,
          "pricing": {
            "regular_price": "24.99",
            "sale_prices": []
          },
          "inventory": {
            "stock_status": true,
            "stocks": [
              {
                "quantity": 50
              }
            ]
          },
          "images": [],
          "attributes": [
            {
              "id": 5,
              "name": "Size",
              "value": "Small"
            },
            {
              "id": 6,
              "name": "Color",
              "value": "Red"
            }
          ]
        }
      ],
      "updated_at": "2026-02-25T16:30:00"
    }
  ]
}
Products API response
  • published: false or is_draft: true → not for sale; purchasable: false → out of stock.
  • The first entry of pricing.sale_prices running now is the sale price (a number, a string or {price, start, end}).
  • inventory.stocks quantities are summed; when empty, stock_status says whether it's in stock.
  • There's no currency field, so the currency set in the dashboard is used.
{
  "id": 1042,
  "deliveryCharge": "60",
  "contact": {
    "name": "Customer Name",
    "phone": "01700000000",
    "address": "House 12, Road 4, Dhanmondi, Dhaka"
  },
  "total_price": 1258,
  "note": "Placed through OmniConva chat, cash on delivery.",
  "payment_method": "cash_on_delivery",
  "payment_status": "unpaid",
  "line_items": [
    {
      "product_id": "6001",
      "sku": "TSHIRT-S-RED",
      "variation_id": "6002",
      "name": "Classic Cotton T-Shirt – Small / Red",
      "price": 599,
      "quantity": 2,
      "image": "https://cdn.yourwebsite.com/tshirt.jpg"
    }
  ],
  "omniconva_order_id": "6a3f0c1e-2b7d-4c1a-9f3e-8d2b1c0a9e77",
  "city": "Dhaka",
  "discount": 0
}
What the Order API receives

id is OmniConva's order number. For a product without variations, variation_id equals product_id. omniconva_order_id, city and discount are additions a site may ignore. The Idempotency-Key header and response rules are the same as Standard's.

11When something fails

  • Order push: if the first attempt fails the order isn't lost — the customer is told the store will confirm it, and it's retried in the background. After the last failure the order is marked Failed, staff are notified, and a Retry push button appears on the Orders page.
  • Import: products that can't be read are skipped and counted in Connections › Logs.
  • Every call has a deadline (15 s for products, 20 s for orders) and a 10 MB response cap.

Still need help?

Email us with your account's mobile number and what you were trying to do.

contact@omniconva.com

Related guides

We use cookies from Google Analytics and the Meta Pixel to see how omniconva.com is used and how our ads perform — only if you agree. Privacy policy