Skip to main content
VIZOCHOK uses server-to-server webhooks to communicate with your backend. This is the same pattern used by Stripe, Shopify, and other SaaS platforms.

​
Why Webhooks?

VIZOCHOK stores your product catalog (names, descriptions, categories) for AI search, but prices and stock live on your side. When the AI finds products matching a customer query, VIZOCHOK calls your webhook to get current prices and availability before showing results. The same approach applies to cart operations: when the AI adds an item to the cart, your backend confirms the action and maintains the authoritative cart state.
1

Customer asks for a product

Customer types “show me milk” in the chat widget.
2

AI searches your catalog

VIZOCHOK searches its catalog database and finds 5 matching milk products.
3

VIZOCHOK calls your products_url webhook

Your backend receives the list of SKUs and returns current prices and availability.
4

Results filtered and displayed

Unavailable products are filtered out. The customer sees only in-stock products with live prices.

​
Webhook Endpoints

You need to implement up to three endpoints on your backend:
WebhookPurposeRequired
Products URLReturns prices and stock for a list of SKUsYes
Cart URLProcesses cart operations (add, remove, update, clear)Recommended
Cart GET URLReturns current cart contents for session initializationOptional

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

​
Setup via API

You can also configure webhooks programmatically: 
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
  }'

​
Testing Webhooks

The admin panel includes a built-in webhook test. You can also test from the API: 
curl -X POST https://api.vizochok.com/api/v1/admin/webhooks/test \
  -H "Authorization: Bearer sk_your_secret_key"
This sends a test request to your products URL with a sample SKU list and reports: 
{
  "ok": true,
  "status_code": 200,
  "response_time_ms": 45
}
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?

​
Error Handling & Retries

VIZOCHOK handles webhook failures gracefully:
  • Products webhook: On timeout or error, all requested products are treated as unavailable. The AI tells the customer that products could not be loaded.
  • Cart webhook: On failure, returns {ok: false, reason: "webhook_timeout"} or {ok: false, reason: "webhook_error"}. The AI informs the customer the operation failed.
  • Retries: VIZOCHOK retries once on 5xx errors or timeouts, with a 1-second delay between attempts.
  • Timeouts: Default is 5 seconds. Configurable per tenant (in the webhook settings).

​
Security

Every webhook request includes an HMAC-SHA256 signature and timestamp. See Signature Verification for the full specification and code examples. Headers included with every request:
HeaderDescription
X-VIZOCHOK-Signaturesha256=<hex_digest> HMAC signature
X-VIZOCHOK-TimestampUnix timestamp (seconds)
Content-Typeapplication/json

​
Implementation Guides

For complete request/response specifications and handler examples:

Products Webhook

Implement the products pricing endpoint.

Cart Webhook

Handle cart add, remove, update, and clear operations.

Signature Verification

Verify HMAC-SHA256 signatures with code examples.

Cart Sync Guide

Understand the full cart synchronization flow.