Webhook

Ricevi notifiche in tempo reale quando si verificano eventi.

Panoramica

I webhook ti permettono di:

• Ricevere notifiche eventi istantanee
• Automatizzare workflow
• Sincronizzare con sistemi esterni
• Costruire integrazioni reattive

Requisito Piano

L'accesso webhook richiede un piano che include funzionalità API.

Come Funzionano i Webhook

1. Configuri un URL endpoint
2. Selezioni gli eventi a cui iscriverti
3. Quando si verificano eventi, inviamo richieste HTTP POST
4. Il tuo server elabora il payload
5. Rispondi con stato 2xx

Eventi Disponibili

Evento	Descrizione
photo_request.created	Nuova richiesta foto creata
photo_request.first_viewed	Richiesta visualizzata per la prima volta
photo_submission.created	Foto inviate (Link Permanenti)
photo_request.submitted	Richiesta una tantum completata
photo_request.expired	Richiesta scaduta senza invio
photo_submission.dropbox_synced	Foto sincronizzata su Dropbox con link condiviso

Creare un Webhook

Passaggi

1. Vai a Webhook nella barra laterale
2. Clicca Crea Webhook
3. Inserisci un nome descrittivo
4. Fornisci l'URL del tuo endpoint
5. Seleziona gli eventi a cui iscriverti
6. Attiva Attivo (default: attivo)
7. Clicca Crea

Requisiti Endpoint

Requisito	Valore
Protocollo	HTTPS richiesto
Accessibilità	Internet pubblico
Risposta	Codice stato 2xx
Timeout	Massimo 30 secondi

Reti Private

Gli indirizzi di rete privati e interni (localhost, 10.x.x.x, 192.168.x.x) non sono permessi.

Payload Webhook

Formato Richiesta

POST /your-endpoint HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Webhook-ID: wh_123456
X-Webhook-Timestamp: 1609459200

Struttura Payload

{
  "event": "photo_request.submitted",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "req_abc123",
    "type": "one_time",
    "instructions": "Invia foto del veicolo",
    "photos": [
      {
        "id": "photo_xyz789",
        "url": "https://...",
        "slot_instructions": "Vista frontale",
        "metadata": {
          "gps_lat": 45.1234,
          "gps_lng": 12.5678,
          "captured_at": "2024-01-15T10:28:00Z"
        }
      }
    ],
    "submitted_at": "2024-01-15T10:30:00Z"
  }
}

Verifica Firma

Perché Verificare

Verifica le firme webhook per assicurarti che:

• La richiesta provenga da Visiono
• Il payload non sia stato manomesso
• Prevenire attacchi replay

Header Firma

X-Webhook-Signature: sha256=abc123def456...

Passaggi Verifica

// Esempio PHP
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = 'your-webhook-secret';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Firma non valida');
}

// Esempio Node.js
const crypto = require('crypto');

const payload = JSON.stringify(req.body);
const signature = req.headers['x-webhook-signature'];
const secret = process.env.WEBHOOK_SECRET;

const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
  return res.status(401).send('Firma non valida');
}

Gestire i Webhook

Testare Webhook

Invia un evento di test:

1. Clicca Test sul webhook
2. Conferma l'azione
3. Controlla stato risposta
4. Visualizza nei log se fallito

Visualizzare Log

Vedi storico consegne:

1. Clicca Log sul webhook
2. Visualizza consegne recenti
3. Controlla stato e risposta
4. Debug errori

Dettagli Log

Ogni log mostra:

• Tipo evento
• Timestamp
• Stato risposta
• Tempo risposta
• Body richiesta/risposta (per debug)

Rigenerare Secret

Ottieni un nuovo signing secret:

1. Clicca Rigenera Secret
2. Conferma l'azione
3. Copia nuovo secret immediatamente
4. Aggiorna il tuo server

Aggiorna Prima il Server

Dopo la rigenerazione, il vecchio secret smette di funzionare. Aggiorna il codice di verifica prima di rigenerare.

Disattivare Webhook

Smetti temporaneamente di ricevere eventi:

1. Clicca Disattiva
2. Conferma l'azione
3. Gli eventi non vengono più inviati
4. Riattiva quando pronto

Eliminare Webhook

Rimuovi permanentemente:

1. Clicca Elimina
2. Conferma l'azione
3. Tutti i log vengono eliminati

Policy Retry

Retry Automatici

Le consegne fallite vengono ritentate:

Tentativo	Ritardo
1	Immediato
2	1 minuto
3	5 minuti
4	30 minuti
5	2 ore

Criteri di Errore

Una consegna fallisce se:

• Timeout connessione (30s)
• Risposta non-2xx
• Errore di rete
• Errore SSL

Dopo Max Retry

Se tutti i retry falliscono:

• L'evento viene marcato come fallito
• Registrato per revisione
• Nessun ulteriore tentativo

Best Practice

Design Endpoint

• Rispondi rapidamente (< 5 secondi)
• Elabora async se necessario
• Restituisci 2xx immediatamente
• Gestisci idempotenza

Gestione Errori

// Pattern raccomandato
app.post('/webhook', async (req, res) => {
  // Verifica firma prima
  if (!verifySignature(req)) {
    return res.status(401).send('Non valido');
  }

  // Conferma immediatamente
  res.status(200).send('OK');

  // Elabora async
  processWebhookAsync(req.body);
});

Idempotenza

Gli eventi potrebbero essere inviati più di una volta. Gestisci i duplicati:

// Controlla se già elaborato
const eventId = req.headers['x-webhook-id'];
if (await isProcessed(eventId)) {
  return res.status(200).send('Già elaborato');
}

// Elabora e marca come gestito
await processEvent(req.body);
await markProcessed(eventId);

Monitoraggio

• Registra tutti i webhook in arrivo
• Alerta sugli errori
• Monitora tempi risposta
• Traccia volumi eventi

Risoluzione Problemi

Non Ricevi Eventi

1. Verifica che il webhook sia attivo
2. Controlla che l'URL endpoint sia corretto
3. Assicurati che HTTPS funzioni
4. Verifica che il server sia accessibile
5. Controlla eventi selezionati

Mismatch Firma

1. Usa il secret corretto
2. Confronta payload completo (non parsato)
3. Controlla problemi encoding
4. Verifica algoritmo HMAC (SHA256)

Timeout

1. Riduci tempo elaborazione
2. Conferma immediatamente
3. Elabora asincronamente
4. Controlla risorse server

Visualizzare Consegne Fallite

1. Vai ai log webhook
2. Filtra per stato (fallito)
3. Visualizza dettagli richiesta/risposta
4. Correggi e ritesta

Limiti Webhook

Per Piano

Piano	Max Webhook
Professional	5 webhook
Enterprise	Illimitati

Rate Limit

Limite	Valore
Eventi per minuto	100
Dimensione payload	1 MB

Pagine Correlate

• Chiavi API - Autenticazione API
• Riferimento API - Documentazione API completa
• Integrazioni - Integrazioni pre-costruite