Webhooks et API - BoothDock Wiki

BoothDock Studio peut informer d'autres programmes de chaque étape d'une session (webhooks) et se laisser piloter par d'autres programmes (API locale). Tu trouves les deux dans la zone d'administration sous Système → Automatisation.

Dans BoothDock Studio 1.4.0 et les versions antérieures, les webhooks s'y appellent encore « Déclencheurs ».

Les webhooks et l'export en temps réel n'existent que sous Windows. L'API locale est disponible depuis la version 1.4.0 aussi sur iPad et iPhone.

Usages typiques : lumière ou DMX synchronisés avec le compte à rebours, un overlay de stream, un compteur à l'entrée – ou un Stream Deck comme télécommande pour la Box.

Système → Automatisation : export en temps réel, webhooks et API locale

Configurer les webhooks

Renseigne le champ Programme, le champ Adresse (URL) ou les deux. À chaque événement, la Box appelle les deux :

Programme – un .exe, .bat ou .cmd. Appel : programme <événement> <param1> <param2> …. Chaque valeur arrive comme argument distinct, même si elle contient des espaces. Le programme démarre sans fenêtre, dans son propre dossier. Pour un script PowerShell (.ps1), passe par un petit .bat placé devant.
Adresse (URL) – http ou https, appelée en GET : https://ton-serveur/hook?event_type=<événement>&param1=…&param2=…. Les valeurs sont encodées pour l'URL ; les paramètres déjà présents dans ton adresse sont conservés.

La session n'attend jamais ton webhook : programme et appel tournent en parallèle, et un appel peut durer au maximum 5 secondes. Envoyer un test envoie immédiatement un session_start – tu vérifies ainsi la connexion sans lancer de session.

Le programme et l'adresse se règlent uniquement directement sur la Box, pas via le Hub : un chemin de programme est un droit d'exécuter quelque chose sur l'ordinateur.

Événements

Événement	Quand	Paramètres
`session_start`	Un invité lance une session, le mode est fixé	1 : mode (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2 : mode BoothDock (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Le compte à rebours commence	1 : secondes
`countdown`	Chaque seconde du compte à rebours	1 : progression en pourcentage (à partir de 0)
`capture_start`	Le compte à rebours est terminé, la prise de vue commence	–
`file_download`	L'appareil a enregistré une photo	1 : nom de fichier, 2 : chemin complet
`processing_start`	Le traitement commence	un nom de fichier par original de l'appareil, en dernière valeur le fichier d'impression (vide pour l'instant)
`sharing_screen`	L'écran de résultat s'affiche (une fois par session)	–
`printing`	Une feuille part vers une imprimante	1 : fichier (vide pour l'instant), 2 : copies, 3 : imprimante
`file_upload`	Un fichier est arrivé dans le Hub (pour chaque fichier)	1 : chemin sur la Box, 2 : lien de galerie, 3 : type (`print`, `photo`, `original`, `animation`, `boomerang`, `video`), 4 : album (nom de l'événement)
`session_end`	La session se termine – terminée, annulée, expirée ou supprimée	–

Exemple de .bat qui consigne chaque événement : echo %DATE% %TIME% %* >> "%~dp0evenements.log"

API locale

D'autres programmes pilotent la Box via HTTP – par exemple un Stream Deck, ton propre script ou une commande 360° sur le téléphone.

Activer : Système → Automatisation → Activer l'API. Par défaut, l'API est désactivée. Port 1500, modifiable.
Adresse : http://localhost:1500/api/<commande> (ou 127.0.0.1). Par défaut, la Box n'accepte que les requêtes de cet ordinateur.
Mot de passe : 16 caractères, affiché dans la même section – copie-le ou génères-en un nouveau. À transmettre via ?password=…, via l'en-tête X-Api-Password ou via Authorization: Bearer …. Seul ping fonctionne sans.
Réponse : toujours HTTP 200 avec du JSON, par exemple {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. IsSuccessful indique si cela a fonctionné, ErrorMessage donne la raison en cas d'erreur. Certaines commandes renvoient en plus Data.

Un appel complet : http://localhost:1500/api/start?mode=print&password=TON-MOT-DE-PASSE

Piloter depuis le réseau (téléphone, tablette, 360°)

Active en plus Accessible aussi depuis le réseau. La Box accepte alors les requêtes des appareils du même Wi-Fi/LAN – jamais depuis Internet.

Adresse pour le téléphone : elle figure dans la ligne d'état, par exemple http://192.168.1.20:1500. L'exemple en dessous affiche alors directement l'adresse correspondante.
Sans saisir d'IP : la Box s'annonce elle-même sur le réseau (mDNS/Bonjour, type de service _boothdock._tcp, nom « BoothDock » suivi du nom de l'ordinateur). Les applis qui la recherchent la trouvent automatiquement.
Blocage : si un appareil envoie dix fois un mauvais mot de passe en dix minutes, il est bloqué pendant 15 minutes. Cet ordinateur lui-même n'est jamais bloqué.
Uniquement sur ton propre réseau : le mot de passe circule en clair sur le réseau. N'utilise le mode réseau que sur ton propre Wi-Fi protégé – pas sur le Wi-Fi invités ouvert du lieu.
Pare-feu : l'installation crée l'autorisation, uniquement pour les réseaux privés. Si la ligne d'état affiche un avertissement du pare-feu, réinstalle BoothDock Studio ou autorise-le dans Windows sous « Autoriser une application via le pare-feu ». Si Windows considère le Wi-Fi comme public, les appareils ne peuvent pas entrer – passe le profil sur Privé dans les propriétés réseau.

Commandes

Commande	Effet
`start?mode=print`	Lance une session. Modes : `print` (photo), `gif`, `boomerang`, `slowmo` (360° ; sans 360°, le boomerang), `video`, `ai`. Fonctionne uniquement depuis l'écran d'accueil, uniquement avec un mode activé et pas quand la Box est verrouillée.
`cancel`	Annule la session en cours et revient à l'écran d'accueil.
`status`	Renvoie dans `Data` : mode invité activé/désactivé, écran actuel, mode, verrouillée oui/non.
`print?count=1`	Réimprime le dernier résultat (1 à 10 feuilles). Les vidéos ne peuvent pas être imprimées.
`lockscreen/show`	Verrouille la Box avec « Un instant – on revient tout de suite. » Le coin admin reste accessible.
`lockscreen/exit`	Lève le verrouillage.
`share/email?email=…`	Envoie le dernier résultat par e-mail – nécessite le couplage au Hub et l'action de résultat « Recevoir par e-mail » (Système → Fonctionnement → Actions du résultat (invité) ; jusqu'à la 1.4.0, l'interrupteur « Photo par e-mail (invité) » sous Design → Écrans).
`share/sms`	N'existe pas ; la réponse le dit honnêtement (`IsSuccessful: false`).
`createtestevent?name=…`	Crée un événement de test et l'active. `Data` contient `eventId` et `eventName`. Sans nom, il reçoit un nom avec la date.
`deletetestevent?eventId=…`	Supprime un événement de test créé via l'API – jamais d'autres événements.
`ping`	Vérifie sans mot de passe si l'API fonctionne.

Si la Box ne répond pas dans les 15 secondes, tu reçois IsSuccessful: false avec une indication.

Export en temps réel

Dans le même onglet, tu choisis un Dossier d'export – par exemple une clé USB ou un dossier cloud (OneDrive, Dropbox). Chaque fichier terminé y arrive aussitôt, trié par événement et par type (impressions, originaux, GIF, vidéos – désactivables séparément). Si la clé manque un moment, la Box rattrape les fichiers ensuite. Si un invité supprime sa session sur la borne, les copies disparaissent aussi.

Démarrage par télécommande

Dans le même onglet, tu associes une touche sous Démarrage par télécommande. Les télécommandes de présentation, boutons USB et pédales envoient le plus souvent la barre d'espace ; elle est préréglée. Sous Démarre, tu choisis ce que la touche déclenche sur l'écran d'accueil : Comme un toucher (déroulement normal) ou directement un mode, par exemple le 360° sur la plateforme. Dans BoothDock Studio 1.4.0 et les versions antérieures, la touche n'existe que pour le 360°, voir 360° / Ralenti.

Dépannage

Rien ne se passe : y a-t-il quelque chose dans le journal ? Les webhooks écrivent dans webhooks.log (jusqu'à la 1.4.0: ausloeser.log), l'API dans lokale-api.log – tous deux dans le dossier %LocalAppData%\Boothdock Studio\logs. Les requêtes refusées (mauvais mot de passe, appareil inconnu) y figurent au maximum une fois par minute.
« Invalid password. » – recopie le mot de passe ; après Nouveau mot de passe, l'ancien n'est plus valable.
« The booth is not on the start screen … » – start ne fonctionne que depuis l'écran d'accueil. D'abord cancel, puis start.
« Too many failed attempts … » – l'appareil a envoyé trop souvent un mauvais mot de passe. Attends 15 minutes et vérifie le mot de passe.
Le téléphone n'atteint pas la Box, alors que tout fonctionne sur l'ordinateur : presque toujours le pare-feu Windows ou un Wi-Fi classé comme public – voir plus haut. La ligne d'état signale les deux cas.