Webhooks

Un webhook informe vos propres systèmes de ce qui se passe dans un espace de travail : validations, nouveaux épisodes, vidéos finalisées, publications mises en ligne et plus encore. ShowBits envoie chaque événement, signé, à votre adresse. Les webhooks sont inclus dans les formules Enterprise et OnPremise ; dans toutes les formules, les connexions pour n8n, Zapier et Make disposent de leurs propres webhooks.

Qui configure
Les administrateurs de l’espace de travail
Formules
Enterprise et OnPremise
Ce que ShowBits envoie
Des événements signés qui désignent les objets par leur identifiant, sans noms, titres ni textes

Ajouter un webhook

Ce sont les administrateurs de l’espace de travail qui ajoutent les webhooks. Votre système a besoin d’une adresse qui accepte les requêtes POST via https et qui est joignable depuis Internet.

  1. Ouvrez Settings → API.
  2. Sous Webhooks, cliquez sur Add webhook.
  3. Saisissez l’adresse de votre système dans Address (https). Elle doit commencer par https://, ne contenir ni nom d’utilisateur ni mot de passe et être joignable depuis Internet.
  4. Si vous le souhaitez, saisissez une Description, par exemple le nom du système.
  5. Sous Events, cochez ce dont votre système a besoin. La case d’un groupe, comme Clips, coche tous ses événements.
  6. Cliquez sur Add.
  7. Cliquez sur Copy et enregistrez le secret dans votre système. ShowBits ne l’affiche que cette seule fois.
  8. Cliquez sur Done.

Un espace de travail compte au maximum 10 webhooks, y compris ceux des connexions n8n, Zapier et Make. Pour n8n, utilisez l’URL de production (Production URL) du nœud Webhook ; la boîte de dialogue vous avertit si vous saisissez son URL de test.

Capture d’écran de ShowBits : Ajouter un webhook

Les événements et leur contenu

Les événements sont répartis dans les groupes Clips, Episodes, Posts, Quote cards, Team, Integrations, Brand kits et Workspace. Par exemple : clip.approved lorsqu’un clip est validé définitivement, clip.forwarded lorsqu’il passe à l’étape de validation suivante, clip.video_ready lorsque sa vidéo est finalisée, episode.analysed, episode.embargo_ended, post.published, post.failed et clip.delivered pour une livraison dans votre MAM ou DAM.

Chaque événement est un POST avec un corps JSON : id (l’identifiant de l’événement), type, occurredAt, workspace (identifiant et slug), object (type et identifiant de l’épisode, du clip ou de la publication), via (app, api, automation ou system) et data, avec quelques champs anodins comme le canal ou l’heure. Les noms, titres et textes n’en font jamais partie ; votre système récupère les détails via l’API REST.

Vérifier la signature

Chaque événement comporte les en-têtes ShowBits-Event (le type de l’événement), ShowBits-Delivery (l’identifiant de l’envoi) et ShowBits-Signature: t=…,v1=…. Vérifiez la signature avant que votre système ne réagisse à un événement.

  1. Lisez le corps de la requête sous forme de texte brut, avant que votre système n’analyse le JSON.
  2. Dans ShowBits-Signature, récupérez t, l’heure en secondes Unix, ainsi que chaque valeur v1.
  3. Calculez un HMAC-SHA256 sur t, un point et le corps brut, avec le secret entier comme clé, whsec_ compris, et écrivez le résultat en hexadécimal.
  4. N’acceptez l’événement que si le résultat correspond à l’une des valeurs v1 ; comparez en temps constant.
  5. Rejetez l’événement si t date de plus de cinq minutes.

Pendant une journée après la création d’un nouveau secret, l’en-tête comporte un second v1, signé avec le secret précédent. Vous trouverez des exemples de code dans la documentation de l’API.

Tester, suspendre et vérifier les envois

Chaque webhook affiche son hôte, son état (Active, Paused ou Paused after failures), la description, le nombre d’événements et le moment où l’adresse a accepté un événement pour la dernière fois.

  1. Cliquez sur Test pour envoyer un événement de test (webhook.test). Il est envoyé même à un webhook suspendu.
  2. Cliquez sur Deliveries pour voir les 20 derniers événements avec leur résultat : accepté (avec le code de statut), en cours de nouvelle tentative (avec le nombre de tentatives et l’erreur) ou abandonné (avec l’erreur).
  3. Cliquez sur Pause pour arrêter l’envoi des événements, et sur Resume pour le reprendre.

Les événements qui surviennent pendant qu’un webhook est suspendu ne sont pas envoyés ultérieurement.

Capture d’écran de ShowBits : Tester, suspendre et vérifier les envois

Créer un nouveau secret

Créez un nouveau secret si l’ancien a pu être divulgué, ou pour le changer de temps en temps. L’ancien secret continue lui aussi de signer pendant une journée, afin que vous puissiez basculer votre système sans interruption.

  1. Cliquez sur New secret au niveau du webhook.
  2. Confirmez avec New secret.
  3. Cliquez sur Copy et enregistrez le nouveau secret dans votre système.
  4. Cliquez sur Done.

Supprimer un webhook

La suppression d’un webhook est définitive : plus aucun événement n’y est envoyé, et les envois en attente sont abandonnés.

  1. Cliquez sur l’icône de corbeille (Delete) au niveau du webhook.
  2. Confirmez avec Delete.

Nouvelles tentatives, suspension automatique et événements en double

Votre adresse doit répondre dans les 10 secondes avec un statut compris entre 200 et 299 ; ShowBits ne suit pas les redirections. Sinon, ShowBits réessaie au bout de 1 minute, 5 minutes, 30 minutes, 2 heures, 6 heures et 24 heures, puis abandonne cet événement. Si l’adresse n’accepte rien pendant trois jours, ShowBits suspend le webhook (Paused after failures) et prévient par e-mail les administrateurs de l’espace de travail. Corrigez le problème au niveau de l’adresse, puis cliquez sur Resume.

Un événement peut arriver plusieurs fois : après une nouvelle tentative, ou sur deux webhooks ayant la même adresse. Reconnaissez les doublons à leur id : il est le même pour chaque tentative et pour chaque webhook.

Questions

L’adresse peut-elle se trouver dans notre réseau interne ?

Non. ShowBits n’envoie qu’à des adresses https joignables depuis Internet, sans nom d’utilisateur ni mot de passe.

Pourquoi un événement ne contient-il pas le titre du clip ?

Les événements ne désignent les objets que par leur identifiant : ainsi, aucun nom, titre ni texte ne quitte ShowBits par ce biais. Avec un jeton, votre système récupère les détails via l’API REST.

Combien de temps les envois sont-ils conservés ?

30 jours. Deliveries affiche les 20 derniers envois d’un webhook.

Notre système peut-il gérer lui-même ses webhooks ?

Oui, via l’API REST, avec un jeton disposant des autorisations webhooks:read et webhooks:write. Le titulaire du jeton doit être administrateur de l’espace de travail.

Nous avons la formule Creator ou Business. Pouvons-nous recevoir des événements ?

Les webhooks sous Settings → API sont inclus dans Enterprise et OnPremise. Dans toutes les formules, les connexions pour n8n, Zapier et Make disposent de leurs propres webhooks, avec la même signature : voir n8n, Zapier et Make.