Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vizochok.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
Setup

​
Admin Panel

1

Open Webhook Settings

Log into the Admin Panel, navigate to Settings > Webhooks.
2

Configure Endpoints

Enter the URLs for your webhook endpoints:
  • 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: How long VIZOCHOK waits for your response (default: 5 seconds)
Webhook URLs must use HTTPS. Private IPs and localhost addresses are rejected for security.
3

Save and Note Your Secret

When you save, VIZOCHOK auto-generates a webhook secret if one doesn’t already exist. This secret is used to sign every webhook request with HMAC-SHA256.You can also provide your own secret or rotate it later.
Webhook settings are also available via the REST API — see the API Reference tab.

​
Testing Webhooks

The Admin Panel includes a built-in webhook test under Settings > Webhooks. Click “Test” to send a test request to your products URL and verify connectivity.
If the test fails, check:
  • Is your endpoint publicly accessible (not behind a VPN or firewall)?
  • Does your server respond within the timeout (default 5 seconds)?
  • Is the URL using HTTPS?
  • If you verify signatures, does your secret match?

​
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)

​
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.