---
title: "Connect your own website (API and webhooks) | OmniConva Help"
description: "Connect a website you built yourself through a Products API, an Order API and webhooks — the full guide for its developers."
url: "https://omniconva.com/docs/custom-website-api"
lang: en
alternate_bn: "https://omniconva.com/bn/docs/custom-website-api"
updated: 2026-10-16
markdown: "https://omniconva.com/docs/custom-website-api.md"
---

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.

[Open in dashboard](https://dashboard.omniconva.com/settings/custom-website)[All guides](https://omniconva.com/docs)

Last updated: 16 October 2026

In this guide

1.  What you need
2.  Laravel site? Use the package
3.  Node.js site? Use the package
4.  Connect in the dashboard
5.  Products API (Standard format)
6.  Product webhooks (website → OmniConva)
7.  Order API (Standard format)
8.  Product Detail API (optional)
9.  Order status updates
10.  Alternative format
11.  When something fails
12.  More help

[← Help center](https://omniconva.com/docs)

## 1What you need

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

| Part | Direction | Required? |
| --- | --- | --- |
| **Products API** — the catalog, page by page | OmniConva → website | Yes |
| **Order API** — when a customer confirms an order in chat | OmniConva → website | Yes |
| **Product Detail API** — a live price and stock check before an order | OmniConva → website | No |
| **Webhooks** — product and order status changes | Website → OmniConva | Strongly 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

| Field | Notes |
| --- | --- |
| `id`, `title` | Required. An `id` never changes; variants need their own `id`. |
| `status` | `active` is for sale; `draft` or anything else is not. |
| `price`, `sale_price` | A `sale_price` only counts when it is below `price`. |
| `in_stock`, `stock_quantity` | Either or both. `stock_quantity: null` means stock isn't counted. |
| `images` | Absolute https URLs; up to 8 are kept. |
| `has_more` | Whether 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-Topic | Body |
| --- | --- |
| `product.created`, `product.updated` | The full product, same shape as in the Products API. |
| `product.deleted` | `{"id": "1001"}` |
| `order.updated` | See 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](mailto:contact@omniconva.com)

### Related guides

[Connect your online store

Connect WooCommerce, Shopify or BitCommerz so products, stock and orders sync on their own — the AI quotes prices and stock from there.](https://omniconva.com/docs/connect-store)[Orders

Every order that came from chat: how they're created, what the statuses mean, and updating your own orders' status.](https://omniconva.com/docs/orders)[Connection logs

The history of product imports, stock updates and orders sent to your store — look here first when sync or orders go wrong.](https://omniconva.com/docs/connection-logs)

---

This page as HTML: https://omniconva.com/docs/custom-website-api
In Bangla: https://omniconva.com/bn/docs/custom-website-api
