Webhooks

Füge unter Settings → Developers → Webhooks einen Endpunkt hinzu (Inhaber und Admins). Er muss eine öffentliche HTTPS-Adresse sein. Wähle, welche Ereignisse er empfängt: Lass All events eingeschaltet (das schließt auch Ereignisse ein, die Pellio später hinzufügt), oder schalte es aus und wähle die gewünschten Ereignisse aus. Pellio zeigt das Signatur-Secret des Endpunkts einmal an.

Jeder Endpunkt listet die Ereignisse auf, die er empfängt, und bietet diese Aktionen:

• Edit events ändert, welche Ereignisse er empfängt. Save events übernimmt die Änderung sofort.
• Send test sendet ein Ereignis webhook.test an diesen Endpunkt, unabhängig davon, welche Ereignisse er empfängt.
• Deliveries zeigt die letzten 50 Versuche (ausstehend, zugestellt oder fehlgeschlagen) und ihre Antworten.
• Rotate secret ersetzt das Signatur-Secret. Das neue wird einmal angezeigt, und das alte funktioniert ab sofort nicht mehr – aktualisiere deinen Endpunkt also direkt.
• Remove beendet das Senden an den Endpunkt.

Über die API: POST /v1/webhooks nimmt url und events entgegen (eine leere Liste bedeutet alle Ereignisse), PATCH /v1/webhooks/{id} ändert events, und POST /v1/webhooks/{id}/rotate-secret gibt ein neues secret zurück.

Ereignisse

Jeder Request-Body hat die Form { "id", "event", "createdAt", "data" }:

event	Wann	data
video.created	Ein Video wird durch Upload, Aufnahme oder Import über eine URL erstellt.	id, title
video.ready	Ein Video wurde verarbeitet, auch nach dem Ersetzen oder Zuschneiden.	id, title, status, version, durationSeconds, width, height, errorMessage
video.failed	Ein neues Video konnte nicht verarbeitet werden.	wie video.ready
video.deleted	Ein Video wird in den Papierkorb verschoben (trashed: true) oder endgültig gelöscht.	id, title, trashed
video.watched	Ein identifizierter Zuschauer (über ein E-Mail-Formular, einen Link mit ?email= oder deine WordPress-Website) startet ein Video, erreicht 25 %, 50 % oder 75 % oder schaut es zu Ende (90 % angesehen, über mehrere Besuche hinweg). Einmal pro Zuschauer, Video und Meilenstein.	video (id, title), viewer (email, name), progress (0, 25, 50, 75, 100), milestone (started, 25%, 50%, 75%, completed), completed
lead.captured	Jemand hat ein E-Mail-Formular abgeschickt.	id, email, name, fields, video (id, title), createdAt

Zustellung

Pellio sendet einen POST mit dem Header User-Agent: Pellio-Webhooks/1 und wartet bis zu 10 Sekunden. Jede 2xx-Antwort gilt als zugestellt. Weiterleitungen werden nicht verfolgt, ein 3xx zählt also als Fehler. Fehlgeschlagene Zustellungen werden insgesamt 6-mal versucht: 20 Sekunden Wartezeit vor dem ersten erneuten Versuch, danach jeweils verdoppelt bis maximal 320 Sekunden.

Signaturen prüfen

Jede Anfrage hat einen Header Pellio-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of "t.body">, berechnet mit dem Secret deines Endpunkts. Prüf ihn gegen den unveränderten Request-Body:

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