Skip to Content
WebhooksDescripción general

Webhooks

Los webhooks te permiten recibir notificaciones en tiempo real sobre eventos que ocurren en tu espacio de trabajo de Ignite. En lugar de hacer polling a la API para detectar cambios, los webhooks envían datos a tu servidor cuando se producen los eventos.

¿Qué son los webhooks?

Los webhooks son callbacks HTTP que se disparan cuando ocurren eventos concretos. Cuando sucede un evento (por ejemplo, que se cree o actualice un video), Ignite envía una solicitud HTTP POST a tu endpoint configurado con información sobre el evento.

Casos de uso

  • Sincronización con el CMS — Mantén tu sistema de gestión de contenido externo alineado con los cambios en los videos
  • Automatización de flujos — Lanza flujos automáticos cuando se crean, actualizan o eliminan videos
  • Notificaciones — Envía avisos a tu equipo cuando termine el procesamiento de un video
  • Analítica — Registra el ciclo de vida de los videos en tu propio sistema de analítica

Cómo funciona

Crear una suscripción a webhooks

Configura una suscripción a webhooks en la interfaz de administración de Ignite. Necesitarás:

  • Una URL en tu servidor que pueda recibir solicitudes HTTP POST
  • Los tipos de evento a los que quieres suscribirte

Recibir eventos

Cuando ocurre un evento al que estás suscrito, Ignite envía una solicitud HTTP POST a tu endpoint con:

  • El tipo de evento en la cabecera X-Webhook-Event
  • Una firma para verificación en la cabecera X-Webhook-Signature
  • Un identificador único de entrega en la cabecera X-Webhook-Delivery-Id
  • El objeto de video completo como cuerpo JSON

Procesar y responder

Tu endpoint debería:

  1. Verificar la firma del webhook
  2. Procesar los datos del evento
  3. Devolver un código de estado 2xx en un plazo de 30 segundos

Los webhooks pueden llegar fuera de orden o entregarse más de una vez. Tu cliente es responsable de comprobar la marca de tiempo updatedAt y el id del video para garantizar el orden correcto y la coherencia de los datos. Compara siempre la marca de tiempo entrante con los datos que tengas guardados antes de aplicar actualizaciones, y usa la cabecera X-Webhook-Delivery-Id para detectar y omitir entregas duplicadas.

Suscripción a webhooks

Una suscripción a webhooks es una configuración que define a dónde deben enviarse los eventos y a cuáles escuchar.

Propiedades de la suscripción

PropiedadTipoDescripción
idstringIdentificador único de la suscripción
urlstringURL del endpoint donde se enviarán los eventos (HTTP o HTTPS)
eventsobjectQué tipos de evento están activados
events.videoCreatedbooleanRecibir eventos cuando se crean videos
events.videoUpdatedbooleanRecibir eventos cuando se actualizan videos
events.videoDeletedbooleanRecibir eventos cuando se eliminan videos
activebooleanSi el webhook está activo en este momento
signingSecretstringSecreto usado para la verificación de firma (generado automáticamente)
workspacestringEl espacio de trabajo al que pertenece este webhook

Ejemplo de objeto de suscripción

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

Formato de la solicitud HTTP

Cuando ocurre un evento, Ignite envía una solicitud POST a tu endpoint:

Cabeceras

CabeceraDescripción
Content-Typeapplication/json
X-Webhook-EventTipo de evento (p. ej., video.created)
X-Webhook-SignatureFirma HMAC-SHA256 para verificación
X-Webhook-Delivery-IdIdentificador único de esta entrega (útil para idempotencia)

Cuerpo

El cuerpo de la solicitud contiene el objeto de video completo en JSON. Consulta la documentación del objeto de video para la estructura completa.

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

Próximos pasos

ConsultasTipos de eventos