Webhooks

Ajoutez un endpoint dans Settings → Developers → Webhooks (propriétaires et administrateurs). Il doit s’agir d’une adresse HTTPS publique. Choisissez les événements qu’il reçoit : laissez All events activé (y compris les événements ajoutés plus tard à Pellio), ou désactivez-le et choisissez les événements voulus. Pellio n’affiche qu’une fois le secret de signature de l’endpoint.

Chaque endpoint liste les événements qu’il reçoit, avec ces actions :

• Edit events modifie les événements reçus. Save events applique le changement immédiatement.
• Send test envoie un événement webhook.test à cet endpoint, quels que soient les événements qu’il reçoit.
• Deliveries affiche les 50 dernières tentatives (en attente, livrées ou en échec) et leurs réponses.
• Rotate secret remplace le secret de signature. Le nouveau ne s’affiche qu’une fois et l’ancien cesse aussitôt de fonctionner : mettez donc votre endpoint à jour sans attendre.
• Remove arrête les envois vers l’endpoint.

Via l’API : POST /v1/webhooks accepte url et events (une liste vide signifie tous les événements), PATCH /v1/webhooks/{id} modifie events, et POST /v1/webhooks/{id}/rotate-secret renvoie un nouveau secret.

Événements

Le corps de chaque requête est { "id", "event", "createdAt", "data" } :

event	Quand	data
video.created	Une vidéo est créée par import, enregistrement ou import depuis une URL.	id, title
video.ready	Le traitement d’une vidéo est terminé, y compris après un remplacement ou un découpage.	id, title, status, version, durationSeconds, width, height, errorMessage
video.failed	Une nouvelle vidéo n’a pas pu être traitée.	comme video.ready
video.deleted	Une vidéo est placée dans la corbeille (trashed: true) ou supprimée définitivement.	id, title, trashed
video.watched	Un spectateur identifié (via un formulaire d’e-mail, un lien ?email= ou votre site WordPress) démarre une vidéo, dépasse 25 %, 50 % ou 75 %, ou la termine (90 % regardés, toutes visites confondues). Une fois par spectateur, par vidéo et par étape.	video (id, title), viewer (email, name), progress (0, 25, 50, 75, 100), milestone (started, 25%, 50%, 75%, completed), completed
lead.captured	Quelqu’un a envoyé un formulaire d’e-mail.	id, email, name, fields, video (id, title), createdAt

Livraison

Pellio envoie une requête POST avec l’en-tête User-Agent: Pellio-Webhooks/1 et attend jusqu’à 10 secondes. Toute réponse 2xx compte comme livrée. Les redirections ne sont pas suivies : une réponse 3xx compte donc comme un échec. Les livraisons en échec sont tentées 6 fois au total, avec 20 secondes d’attente avant la première nouvelle tentative, puis un délai qui double jusqu’à 320 secondes.

Vérifier les signatures

Chaque requête comporte un en-tête Pellio-Signature : t=<unix time>,v1=<hex HMAC-SHA256 of "t.body">, calculé avec le secret de votre endpoint. Vérifiez-le à partir du corps brut de la requête :

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