Webhooks

Adicione um endpoint em Settings → Developers → Webhooks (proprietários e administradores). Ele precisa ser um endereço HTTPS público. Escolha quais eventos ele recebe: deixe All events ativado (isso inclui eventos adicionados ao Pellio no futuro) ou desative e selecione os eventos que você quer. O Pellio mostra o segredo de assinatura do endpoint uma única vez.

Cada endpoint lista os eventos que recebe, com estas ações:

• Edit events muda os eventos que ele recebe. Save events aplica a mudança na hora.
• Send test envia um evento webhook.test para aquele endpoint, independentemente dos eventos que ele recebe.
• Deliveries mostra as últimas 50 tentativas (pendentes, entregues ou com falha) e suas respostas.
• Rotate secret substitui o segredo de assinatura. O novo é mostrado uma única vez e o antigo para de funcionar imediatamente, então atualize seu endpoint na hora.
• Remove para de enviar para o endpoint.

Pela API: POST /v1/webhooks recebe url e events (uma lista vazia significa todos os eventos), PATCH /v1/webhooks/{id} altera events, e POST /v1/webhooks/{id}/rotate-secret retorna um novo secret.

Eventos

Todo corpo de requisição é { "id", "event", "createdAt", "data" }:

event	Quando	data
video.created	Um vídeo é criado por upload, gravação ou importação a partir de uma URL.	id, title
video.ready	Um vídeo terminou de ser processado, inclusive depois de uma substituição ou de um corte.	id, title, status, version, durationSeconds, width, height, errorMessage
video.failed	Não foi possível processar um vídeo novo.	igual a video.ready
video.deleted	Um vídeo foi movido para a lixeira (trashed: true) ou excluído definitivamente.	id, title, trashed
video.watched	Um espectador identificado (por um formulário de e-mail, um link com ?email= ou pelo seu site WordPress) começa um vídeo, passa de 25%, 50% ou 75%, ou termina (90% assistido, somando visitas). Uma vez por espectador, vídeo e marco.	video (id, title), viewer (email, name), progress (0, 25, 50, 75, 100), milestone (started, 25%, 50%, 75%, completed), completed
lead.captured	Alguém enviou um formulário de e-mail.	id, email, name, fields, video (id, title), createdAt

Entrega

O Pellio envia um POST com o cabeçalho User-Agent: Pellio-Webhooks/1 e espera até 10 segundos. Qualquer resposta 2xx conta como entregue. Redirecionamentos não são seguidos, então um 3xx conta como falha. Entregas com falha são tentadas 6 vezes no total, esperando 20 segundos antes da primeira nova tentativa e dobrando até 320 segundos.

Como verificar assinaturas

Cada requisição tem um cabeçalho Pellio-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of "t.body">, usando o segredo do seu endpoint. Verifique-o contra o corpo bruto da requisição:

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));
}