Webhooks

Añade un endpoint en Settings → Developers → Webhooks (propietarios y administradores). Tiene que ser una dirección HTTPS pública. Elige qué eventos recibe: deja activado All events (incluye también los eventos que se añadan a Pellio más adelante), o desactívalo y elige los eventos que quieras. Pellio te muestra el secreto de firma del endpoint una sola vez.

Cada endpoint muestra los eventos que recibe, con estas acciones:

• Edit events cambia los eventos que recibe. Save events aplica el cambio al momento.
• Send test envía un evento webhook.test a ese endpoint, sean cuales sean los eventos que recibe.
• Deliveries muestra los últimos 50 intentos de envío (pendientes, entregados o fallidos) y sus respuestas.
• Rotate secret sustituye el secreto de firma. El nuevo se muestra una sola vez y el anterior deja de funcionar inmediatamente, así que actualiza tu endpoint enseguida.
• Remove deja de enviar eventos al endpoint.

Desde la API: POST /v1/webhooks recibe url y events (una lista vacía significa todos los eventos), PATCH /v1/webhooks/{id} cambia events, y POST /v1/webhooks/{id}/rotate-secret devuelve un nuevo secret.

Eventos

El cuerpo de cada petición es { "id", "event", "createdAt", "data" }:

event	Cuándo	data
video.created	Se crea un vídeo al subirlo, grabarlo o importarlo desde una URL.	id, title
video.ready	Un vídeo ha terminado de procesarse, también después de sustituirlo o recortarlo.	id, title, status, version, durationSeconds, width, height, errorMessage
video.failed	No se ha podido procesar un vídeo nuevo.	igual que video.ready
video.deleted	Un vídeo se mueve a la papelera (trashed: true) o se elimina definitivamente.	id, title, trashed
video.watched	Un espectador identificado (por un formulario de email, un enlace con ?email= o tu web de WordPress) empieza un vídeo, pasa del 25%, el 50% o el 75%, o lo termina (90% visto, sumando todas sus visitas). Una vez por espectador, vídeo e hito.	video (id, title), viewer (email, name), progress (0, 25, 50, 75, 100), milestone (started, 25%, 50%, 75%, completed), completed
lead.captured	Alguien ha enviado un formulario de email.	id, email, name, fields, video (id, title), createdAt

Entrega

Pellio envía un POST con la cabecera User-Agent: Pellio-Webhooks/1 y espera hasta 10 segundos. Cualquier respuesta 2xx cuenta como entregada. No se siguen las redirecciones, así que un 3xx cuenta como fallo. Las entregas fallidas se intentan 6 veces en total: el primer reintento llega a los 20 segundos y la espera se va duplicando hasta 320 segundos.

Verificar las firmas

Cada petición lleva una cabecera Pellio-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of "t.body">, calculada con el secreto de tu endpoint. Verifícala con el cuerpo de la petición tal cual llega, sin procesar:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(header, rawBody, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // 5-minute tolerance
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}