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 migrateclass 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])
));
}
}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);
}
}- 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:testchecks that everything is wired up.
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));4Connect in the dashboard
- Press Connect on the Custom website row under Connections.
- Enter the Website URL, the currency and the API format.
- 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. - Enter the Order API URL and headers. Optionally send one with Send test order.
- Press Connect website. The product import starts on its own, and the Webhooks section shows your webhook URL, token and signing secret.
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
}| 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."
}{
"order_id": "W-5531",
"order_number": "5531"
}Idempotency-Key. If you've seen the key before, return the first order (2xx, or 409 with its id) instead of creating another."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"
}
]
}published: falseoris_draft: true→ not for sale;purchasable: false→ out of stock.- The first entry of
pricing.sale_pricesrunning now is the sale price (a number, a string or{price, start, end}). inventory.stocksquantities are summed; when empty,stock_statussays 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
}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