Skip to main content
VIZOCHOK uses server-to-server HTTP webhooks to communicate with your backend. This is the same architecture used by Stripe, Shopify, and other modern SaaS platforms — your backend stays in control of prices, stock, and cart state at all times.

​
Why Webhooks?

VIZOCHOK stores your product catalog (names, descriptions, categories) for AI-powered semantic search. However, prices and stock availability change frequently and must come from your system of record. Instead of syncing prices to VIZOCHOK, your backend provides them on-demand when the AI needs them:
1

AI finds matching SKUs

The Catalog DB stores product names, descriptions, and embeddings. When a customer asks for a product, the AI searches and finds matching SKUs.
2

VIZOCHOK calls your products_url webhook

An HTTP POST request with the matching SKUs is sent to your backend to get current prices and stock.
3

Filter unavailable products

Products not returned by your webhook or marked as out of stock are filtered out.
4

Show results to customer

Only available products with live prices are displayed to the customer.

​
Webhook Types

​
Products Webhook (Required)

Called when the AI needs current prices and availability for specific products. When it fires: After the AI searches the catalog and finds matching products, before showing them to the customer.
1

AI searches catalog

AI searches “milk” and finds SKUs: milk-001, milk-002, milk-003.
2

VIZOCHOK calls your webhook

POST https://your-api.com/api/vizochok/check-products
{
  "skus": ["milk-001", "milk-002", "milk-003"],
  "store_id": "store-1"
}
3

Your backend responds with prices

{
  "products": [
    {"sku": "milk-001", "price": 45.90, "in_stock": true},
    {"sku": "milk-002", "price": 52.00, "in_stock": true, "promo_price": 42.00, "promo_label": "-19%"},
    {"sku": "milk-003", "price": 38.50, "in_stock": false}
  ]
}
4

VIZOCHOK filters and displays

milk-003 is filtered out (out of stock). milk-001 and milk-002 are shown to the customer with correct prices.
Products not returned in the response are treated as unavailable and excluded from results. See Products Webhook for the complete specification.
Called when the AI performs a cart operation (add, remove, update quantity, clear). When it fires: After the AI decides to modify the cart, before confirming the change to the customer.
1

AI decides to add product

AI decides to add milk-001 to cart.
2

VIZOCHOK calls your cart webhook

POST https://your-api.com/api/vizochok/cart
{
  "action": "add",
  "store_id": "store-1",
  "session_id": "user-123",
  "sku": "milk-001",
  "name": "Молоко Lactel 2.5%",
  "quantity": 1,
  "price": 45.90
}
3

Your backend responds

Success: {"ok": true} — AI confirms: “Added!”Failure: {"ok": false, "reason": "out_of_stock"} — AI: “Sorry, that’s out of stock. Want to try another brand?”
See Cart Webhook for all four operations.

​
Cart GET Webhook (Optional)

Called once when a new conversation starts, to load the customer’s existing cart. When it fires: On the first message of a new conversation, if cart_get_url is configured.
1

New conversation starts

Customer sends first message. VIZOCHOK checks if cart_get_url is configured.
2

VIZOCHOK calls your cart GET webhook

GET https://your-api.com/api/vizochok/cart/items
  ?store_id=store-1&session_id=user-123
3

Your backend returns current cart

{
  "items": [
    {"sku": "bread-01", "name": "Хліб", "price": 32.00, "quantity": 1, "unit": "pcs"}
  ]
}
AI now knows the customer already has bread and can reference it in conversation.

​
Request Signing

Every webhook request includes HMAC-SHA256 signature headers:
HeaderValue
X-VIZOCHOK-Signaturesha256=<hex_digest>
X-VIZOCHOK-TimestampUnix timestamp (seconds)
Content-Typeapplication/json
The signature covers both the timestamp and the request body to prevent replay attacks. See Signature Verification for implementation details.

​
Error Handling

ScenarioVIZOCHOK Behavior
Products webhook timeout/errorAll products treated as unavailable
Cart webhook timeout/error{ok: false, reason: "webhook_timeout"} — AI tells customer the operation failed
5xx responseRetries once with 1-second delay
Non-200 responseTreats as failure, no retry
Products not in responseFiltered out (treated as unavailable)

​
Configuration

Webhooks are configured per tenant, either via the admin panel or the API: 
# Get current webhook config
curl https://api.vizochok.com/api/v1/admin/webhooks \
  -H "Authorization: Bearer sk_your_secret_key"

# Update webhook config
curl -X PATCH https://api.vizochok.com/api/v1/admin/webhooks \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "products_url": "https://your-api.com/api/vizochok/check-products",
    "cart_url": "https://your-api.com/api/vizochok/cart",
    "cart_get_url": "https://your-api.com/api/vizochok/cart/items",
    "timeout_seconds": 5.0
  }'
A webhook secret is auto-generated when you first save webhook settings. You can also provide your own secret or rotate it later. The secret is used for HMAC-SHA256 signing.

​
Next Steps

Products Webhook

Full request/response specification with handler examples.

Cart Webhook

Handle all four cart operations with validation.

Signature Verification

HMAC-SHA256 verification in Python, Node.js, and Go.