Skip to Content
WebhooksPanoramica

Webhook

I webhook ti permettono di ricevere notifiche in tempo reale sugli eventi che avvengono nel tuo workspace Ignite. Invece di interrogare ripetutamente l’API per i cambiamenti, i webhook inviano i dati al tuo server quando si verifica un evento.

Cosa sono i webhook?

I webhook sono callback HTTP attivati quando si verificano eventi specifici. Quando succede qualcosa (ad esempio la creazione o l’aggiornamento di un video), Ignite invia una richiesta HTTP POST all’endpoint che hai configurato con le informazioni sull’evento.

Casi d’uso

  • Sincronizzazione CMS — Tieni allineato il tuo sistema di gestione contenuti esterno con le modifiche ai video
  • Automazione dei flussi di lavoro — Attiva flussi automatici quando i video vengono creati, aggiornati o eliminati
  • Notifiche — Invia avvisi al team quando l’elaborazione del video è completata
  • Analytics — Traccia gli eventi del ciclo di vita dei video nel tuo sistema di analytics

Come funziona

Creare una sottoscrizione webhook

Configura una sottoscrizione webhook nell’Admin UI di Ignite. Devi indicare:

  • L’URL di un endpoint sul tuo server in grado di ricevere richieste HTTP POST
  • I tipi di evento a cui vuoi iscriverti

Ricevere eventi

Quando si verifica un evento a cui sei iscritto, Ignite invia una richiesta HTTP POST al tuo endpoint con:

  • Il tipo di evento nell’intestazione X-Webhook-Event
  • Una firma per la verifica nell’intestazione X-Webhook-Signature
  • Un ID di consegna univoco nell’intestazione X-Webhook-Delivery-Id
  • L’intero oggetto video come body JSON

Elaborare e rispondere

Il tuo endpoint dovrebbe:

  1. Verificare la firma del webhook
  2. Elaborare i dati dell’evento
  3. Restituire un codice di stato 2xx entro 30 secondi

I webhook possono arrivare fuori ordine o essere consegnati più di una volta. Il tuo client deve controllare il timestamp updatedAt e l’id del video per garantire ordine e coerenza dei dati. Confronta sempre il timestamp in arrivo con i dati salvati prima di applicare gli aggiornamenti e usa l’intestazione X-Webhook-Delivery-Id per rilevare e ignorare consegne duplicate.

Sottoscrizione webhook

Una sottoscrizione webhook è una configurazione che definisce dove inviare gli eventi e quali eventi ascoltare.

Proprietà della sottoscrizione

ProprietàTipoDescrizione
idstringIdentificatore univoco della sottoscrizione
urlstringURL dell’endpoint dove verranno inviati gli eventi (HTTP o HTTPS)
eventsobjectQuali tipi di evento sono abilitati
events.videoCreatedbooleanRicevi eventi quando vengono creati i video
events.videoUpdatedbooleanRicevi eventi quando i video vengono aggiornati
events.videoDeletedbooleanRicevi eventi quando i video vengono eliminati
activebooleanSe il webhook è attualmente attivo
signingSecretstringChiave segreta usata per la verifica della firma (generata automaticamente)
workspacestringIl workspace a cui appartiene questo webhook

Oggetto sottoscrizione di esempio

{
  "id": "507f1f77bcf86cd799439011",
  "url": "https://your-server.com/webhook",
  "events": {
    "videoCreated": true,
    "videoUpdated": true,
    "videoDeleted": false
  },
  "active": true,
  "signingSecret": "whsec_abc123...",
  "workspace": "507f1f77bcf86cd799439000"
}

Formato della richiesta HTTP

Quando si verifica un evento, Ignite invia una richiesta POST al tuo endpoint:

Intestazioni

IntestazioneDescrizione
Content-Typeapplication/json
X-Webhook-EventIl tipo di evento (es. video.created)
X-Webhook-SignatureFirma HMAC-SHA256 per la verifica
X-Webhook-Delivery-IdIdentificatore univoco di questa consegna (utile per l’idempotenza)

Corpo

Il corpo della richiesta contiene l’intero oggetto video in JSON. Per la struttura completa vedi la documentazione sull’oggetto video.

{
  "id": "507f1f77bcf86cd799439011",
  "title": "My Video",
  "status": "COMPLETE",
  "visibility": "public",
  "duration": 120,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  // ... all other video properties
}

Passi successivi

QueryTipi di eventi