Tipos de eventos

Los webhooks de Ignite admiten tres tipos de evento para el ciclo de vida de los videos. Puedes suscribirte a cualquier combinación de ellos al crear una suscripción a webhooks.

Eventos disponibles

`video.created`

Se dispara cuando se crea un video nuevo en tu espacio de trabajo.

Cuándo ocurre:

Se crea un objeto de video nuevo vía API
Se sube un video desde la interfaz de administración

Cuerpo (payload): El objeto de video completo con todos los valores iniciales. En subidas por API, status suele ser NO_FILE hasta que termina la subida del archivo; entonces comienza la codificación (PROGRESSING).

`video.updated`

Se dispara cuando se modifica cualquier propiedad de un video.

Cuándo ocurre:

Se actualizan metadatos del video (título, descripción, visibilidad, etc.)
Actualizaciones del progreso de codificación (statusProgress mientras status es PROGRESSING). Pueden dispararse con frecuencia; debounce las actualizaciones de la UI si es necesario.
La codificación del video finaliza (el estado pasa a COMPLETE) o falla (ERROR)
Se añaden o modifican Text tracks o capítulos
Cambian categorías o etiquetas
Se actualiza la miniatura

Cuerpo (payload): El objeto de video completo con todos los valores actuales tras la actualización, incluidos statusProgress, errorCode y errorMessage. Consulta Estado de codificación.

`video.deleted`

Se dispara cuando se elimina un video de tu espacio de trabajo.

Cuándo ocurre:

Se elimina un video vía API
Se elimina un video desde la interfaz de administración

Cuerpo (payload): El objeto de video completo tal como existía antes de la eliminación.

Estructura del cuerpo del evento

Todos los eventos entregan el objeto de video completo como cuerpo de la solicitud. El tipo de evento va en la cabecera X-Webhook-Event, no en el cuerpo.

Ejemplo: video.created

Cabeceras:


POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
X-Webhook-Event: video.created
X-Webhook-Signature: t=1705316400000,v1=abc123...
X-Webhook-Delivery-Id: del_507f1f77bcf86cd799439011

Cuerpo:


{
  "id": "507f1f77bcf86cd799439011",
  "status": "NO_FILE",
  "statusProgress": 0,
  "errorCode": null,
  "errorMessage": null,
  "visibility": "private",
  "title": "My New Video",
  "description": "",
  "duration": 0,
  "workspace": "507f1f77bcf86cd799439000",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Ejemplo: video.updated

Cabeceras:


POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
X-Webhook-Event: video.updated
X-Webhook-Signature: t=1705316500000,v1=def456...
X-Webhook-Delivery-Id: del_507f1f77bcf86cd799439012

Cuerpo:


{
  "id": "507f1f77bcf86cd799439011",
  "status": "COMPLETE",
  "statusProgress": 100,
  "errorCode": null,
  "errorMessage": null,
  "visibility": "public",
  "title": "My New Video",
  "description": "A great video about something",
  "duration": 120,
  "fps": 30,
  "orientation": "landscape",
  "src": {
    "thumbnails": [
      {
        "name": "1080p", "width": 1920, "height": 1080,
        "formats": {
          "jpeg": { "url": "https://cdn.ignite.video/.../a1b2c3d4-1080p.jpg", "fileSize": 9180 },
          "webp": { "url": "https://cdn.ignite.video/.../a1b2c3d4-1080p.webp", "fileSize": 4256 }
        }
      },
      // ... additional resolutions
    ],
    "thumbnailUrl": "https://cdn.ignite.video/.../a1b2c3d4-1080p.jpg",
    "abr": {
      "resolution": "auto",
      "description": "Adaptive Bitrate Streaming (ABR)",
      "url": "https://cdn.ignite.video/.../master.m3u8",
      "maxWidth": 1920,
      "maxHeight": 1080
    },
    "hls": [...],
    "mp4": [...]
  },
  "workspace": "507f1f77bcf86cd799439000",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:35:00.000Z"
}

Ejemplo: video.deleted

Cabeceras:


POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
X-Webhook-Event: video.deleted
X-Webhook-Signature: t=1705316600000,v1=ghi789...
X-Webhook-Delivery-Id: del_507f1f77bcf86cd799439013

Cuerpo:


{
  "id": "507f1f77bcf86cd799439011",
  "status": "COMPLETE",
  "visibility": "public",
  "title": "My New Video",
  "description": "A great video about something",
  "duration": 120,
  "workspace": "507f1f77bcf86cd799439000",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:35:00.000Z"
}

Buenas prácticas

Gestionar todos los eventos suscritos

Comprueba siempre la cabecera X-Webhook-Event y trata cada tipo de evento de forma adecuada:


const eventType = request.headers['x-webhook-event'];
 
switch(eventType) {
  case 'video.created':
    // Handle new video
    break;
  case 'video.updated':
    // Handle video update
    break;
  case 'video.deleted':
    // Handle video deletion
    break;
  default:
    console.log('Unknown event type:', eventType);
}

Usar el ID de entrega para idempotencia

La cabecera X-Webhook-Delivery-Id contiene un identificador único para cada entrega de webhook. Guarda los IDs de entrega ya procesados para evitar procesar de nuevo en caso de reintentos:


const deliveryId = request.headers['x-webhook-delivery-id'];
 
if (await hasBeenProcessed(deliveryId)) {
  return res.status(200).json({ received: true, duplicate: true });
}
 
// Process the event...
await markAsProcessed(deliveryId);