Event-based ingestion allows you to send real-time updates to Youzu.ai whenever products are created, updated, or deleted in your system.

Benefits of Using WebhooksCopied!

• Real-time synchronization - Product data is updated immediately
• Reduced API load - Only changed data is transmitted
• Automatic management - No need to schedule regular imports
• Simplified workflow - Changes in your system trigger automatic updates to Youzu.ai

Setting Up WebhooksCopied!

1. In your Youzu.ai dashboard, navigate to Settings > Webhooks
2. Click Add Webhook Endpoint
3. Enter the following information:
   • Event Types: Select which events to receive (product.created, product.updated, product.deleted)
   • Secret Key: Generate a secret key to secure webhook communications
   • URL: The endpoint URL from your system that will receive the webhook data

Supported Event TypesCopied!

Event Type	Description	When It's Triggered
product.created	New product added	When a product is created in your catalog
product.updated	Existing product modified	When product details change
product.deleted	Product removed	When a product is deleted or archived
product.inventory_updated	Stock level changed	When inventory levels change
product.price_updated	Price changed	When a product's price is modified

Webhook Payload FormatCopied!

When an event occurs, Youzu.ai will send a POST request to your endpoint with the following payload structure:

{
  "event": "product.created",
  "timestamp": "2025-03-16T12:30:19+01:00",
  "data": {
    "product_id": "prod_12345",
    "name": "Ergonomic Office Chair",
    "description": "Premium office chair with lumbar support",
    "price": 299.99,
    "currency": "USD",
    "images": [
      {
        "url": "<https://example.com/images/chair_front.jpg>",
        "position": 1,
        "alt": "Front view of office chair"
      },
      {
        "url": "<https://example.com/images/chair_side.jpg>",
        "position": 2,
        "alt": "Side view of office chair"
      }
    ],
    "categories": ["Furniture", "Office"],
    "tags": ["ergonomic", "office", "comfortable"],
    "variants": [
      {
        "id": "var_789",
        "attributes": {
          "color": "Black",
          "material": "Leather"
        }
      }
    ],
    "metadata": {
      "inventory_count": 42,
      "featured": true
    }
  }
}
json Copy Copied!

Webhook SecurityCopied!

To verify that incoming webhooks are genuinely from Youzu.ai:

1. Youzu.ai includes a X-Youzu-Signature header with each webhook request
2. This signature is an HMAC SHA-256 hash of the request body using your secret key
3. Verify this signature in your webhook handler before processing the data

Signature Verification ExamplesCopied!

Node.js

const crypto = require('crypto');

function verifyWebhookSignature(requestBody, signature, secretKey) {
  const hmac = crypto.createHmac('sha256', secretKey);
  const calculatedSignature = hmac.update(requestBody).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(calculatedSignature, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

// Express.js example
app.post('/youzu-webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-youzu-signature'];
  const isValid = verifyWebhookSignature(req.body, signature, process.env.YOUZU_WEBHOOK_SECRET);
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  const payload = JSON.parse(req.body.toString());
  // Process the webhook payload
  
  res.status(200).send('Webhook received');
});
javascript Copy Copied!

PHP

<?php
// Get the webhook signature from the headers
$signature = $_SERVER['HTTP_X_YOUZU_SIGNATURE'] ?? '';

// Get the raw request body
$payload = file_get_contents('php://input');

// Calculate the expected signature
$secretKey = getenv('YOUZU_WEBHOOK_SECRET');
$calculatedSignature = hash_hmac('sha256', $payload, $secretKey);

// Verify the signature
if (hash_equals($calculatedSignature, $signature)) {
    $data = json_decode($payload, true);
    // Process the webhook payload
    http_response_code(200);
    echo "Webhook received";
} else {
    http_response_code(401);
    echo "Invalid signature";
}
php Copy Copied!

Python

import hmac
import hashlib
import os
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/youzu-webhook', methods=['POST'])
def youzu_webhook():
    signature = request.headers.get('X-Youzu-Signature')
    payload = request.data
    
    secret_key = os.environ.get('YOUZU_WEBHOOK_SECRET')
    calculated_signature = hmac.new(
        key=secret_key.encode('utf-8'),
        msg=payload,
        digestmod=hashlib.sha256
    ).hexdigest()
    
    if hmac.compare_digest(calculated_signature, signature):
        # Process the webhook payload
        return jsonify(success=True), 200
    else:
        return jsonify(error="Invalid signature"), 401
python Copy Copied!

Responding to WebhooksCopied!

Your webhook endpoint should respond with an HTTP 200 status code to acknowledge receipt of the webhook. If Youzu.ai doesn't receive a 200 response, it will retry the webhook delivery with an exponential backoff strategy.

Best PracticesCopied!

1. Process webhooks asynchronously - Acknowledge receipt immediately, then process in the background
2. Implement idempotency - Handle potential duplicate webhook deliveries gracefully
3. Monitor failures - Set up alerts for webhook processing errors
4. Keep secret keys secure - Rotate webhook secrets periodically for enhanced security

TroubleshootingCopied!

Issue	Possible Solution
Missing webhooks	Check firewall settings and ensure your endpoint is publicly accessible
Signature verification failures	Verify you're using the correct secret key and comparing in a secure way
Webhook timeouts	Ensure your endpoint responds quickly, ideally under 3 seconds

For further assistance with webhook setup, contact our support team at support@youzu.ai.