Event-Based Ingestion (Webhooks)

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 Webhooks

• 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 Webhooks

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 Types

Webhook Payload Format

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
    }
  }
}

Webhook Security

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 Examples

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');
});

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

Responding to Webhooks

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.