Zytaro - Webhooks - Notifiche Real-Time

Cosa sono i Webhooks?

I webhooks sono notifiche HTTP POST che Zytaro invia automaticamente al tuo server quando accade un evento specifico. Invece di controllare continuamente l'API (polling), ricevi aggiornamenti in tempo reale.

✅ Vantaggi

• Notifiche istantanee
• Nessun polling necessario
• Riduce il carico sul server
• Integrazione più efficiente

🔒 Sicurezza

• Signature HMAC-SHA256
• Verifica dell'autenticità
• HTTPS obbligatorio
• Secret univoco per webhook

Come Funziona

1

Registra il tuo Webhook

Crea un webhook tramite API specificando l'URL del tuo endpoint e gli eventi a cui vuoi iscriverti.

POST /api/v1/webhooks
Content-Type: application/json
X-API-Key: your_api_key

{
  "url": "https://tuoserver.com/webhooks/zytaro",
  "events": ["order.created", "order.shipped"]
}

2

Ricevi il Secret

Zytaro ti fornisce un secret univoco. Conservalo in sicurezza - ti servirà per verificare le signature.

⚠️ Il secret viene mostrato solo una volta alla creazione del webhook.

3

Ricevi le Notifiche

Quando un evento accade, Zytaro invia una richiesta POST al tuo endpoint con tutti i dettagli.

POST https://tuoserver.com/webhooks/zytaro
Headers:
  Content-Type: application/json
  X-Zytaro-Event: order.created
  X-Zytaro-Signature: abc123def456...
  
Body:
{
  "event": "order.created",
  "timestamp": "2024-01-15T12:30:00Z",
  "data": {
    "order_id": 123,
    "user_id": 45,
    "total": 99.99,
    "items": [...]
  }
}

4

Verifica la Signature

Verifica sempre la signature HMAC per assicurarti che la richiesta provenga da Zytaro.

// PHP Example
$signature = $_SERVER['HTTP_X_ZYARO_SIGNATURE'] ?? '';
$payload = file_get_contents('php://input');
$secret = 'your_webhook_secret';

$expected = hash_hmac('sha256', $payload, $secret);
if (hash_equals($expected, $signature)) {
  // Webhook autentico - procedi con l'elaborazione
} else {
  http_response_code(401);
  die('Invalid signature');
}

Eventi Supportati

📦 Ordini

order.created - Nuovo ordine creato
order.updated - Ordine aggiornato
order.shipped - Ordine spedito
order.completed - Ordine completato
order.cancelled - Ordine cancellato

🏭 Fornitori

supplier.task.created - Nuovo task creato
supplier.task.assigned - Task assegnato
supplier.task.completed - Task completato
supplier.task.failed - Task fallito

📄 Materiali

material.created - Nuovo materiale
material.updated - Materiale aggiornato
material.price_changed - Prezzo cambiato

🎨 Template

template.created - Nuovo template
template.updated - Template aggiornato
template.published - Template pubblicato

📦 Prodotti

product.created - Nuovo prodotto creato
product.updated - Prodotto aggiornato
product.deleted - Prodotto eliminato
product_category.created - Nuova categoria creata
product_category.updated - Categoria aggiornata
product_category.deleted - Categoria eliminata

🎬 Scene Composer

scene.created - Nuova scena creata
scene.updated - Scena aggiornata
scene.deleted - Scena eliminata
composed_object.created - Nuovo oggetto composto
composed_object.updated - Oggetto composto aggiornato
composed_object.deleted - Oggetto composto eliminato
scene_asset.uploaded - Nuovo asset caricato
scene_asset.deleted - Asset eliminato

Esempi di Codice

PHP

<?php
// Definisci il secret del webhook (da variabile d'ambiente o config)
$webhookSecret = getenv('ZYARO_WEBHOOK_SECRET') ?: 'your_webhook_secret_here';

// Funzione per verificare la signature HMAC
function verifyWebhook($payload, $signature, $secret) {
    $expected = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

// Ricevi il payload del webhook
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_ZYARO_SIGNATURE'] ?? '';

// Verifica la signature
if (!verifyWebhook($payload, $signature, $webhookSecret)) {
    http_response_code(401);
    die('Invalid signature');
}

// Decodifica i dati JSON
$data = json_decode($payload, true);

// Processa l'evento
if ($data['event'] === 'order.created') {
    $orderId = $data['data']['order_id'];
    $userId = $data['data']['user_id'];
    // Gestisci il nuovo ordine
    // ...
}

// Rispondi con 200 OK
http_response_code(200);
echo 'OK';
?>

Node.js (Express)

const crypto = require('crypto');
const express = require('express');
const app = express();

// Funzione per verificare la signature HMAC
function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// Endpoint per ricevere webhooks
app.post('/webhooks/zytaro', 
  express.raw({ type: 'application/json' }), 
  (req, res) => {
    const signature = req.headers['x-zytaro-signature'];
    const secret = process.env.ZYTARO_WEBHOOK_SECRET;
    
    // Verifica la signature
    if (!verifyWebhook(req.body, signature, secret)) {
      return res.status(401).send('Invalid signature');
    }
    
    // Decodifica i dati JSON
    const data = JSON.parse(req.body);
    
    // Processa l'evento
    if (data.event === 'order.created') {
      const orderId = data.data.order_id;
      const userId = data.data.user_id;
      // Gestisci il nuovo ordine
      // ...
    }
    
    // Rispondi con 200 OK
    res.status(200).send('OK');
  }
);

Pronto a Iniziare?

Consulta la documentazione completa dell'API per tutti i dettagli tecnici.

📚 Documentazione API 🔗 Docs Completi

Event-Driven Webhooks