← Alle artikelen

BoothDock · Wiki

Webhooks en API

BoothDock Studio kan andere programma's over elke stap van een sessie informeren (Webhooks) en zich door andere programma's laten aansturen (lokale API). Beide vind je in het beheerdergedeelte onder Systeem → Automatisering.

In BoothDock Studio 1.4.0 en ouder heten de webhooks daar nog „Triggers”.

Webhooks zijn er onder Windows en vanaf versie 1.5.10 ook op iPad, iPhone en Mac. De lokale API is er vanaf versie 1.4.0 ook op iPad, iPhone en Mac, de realtime-export vanaf versie 1.5.2.

Typische toepassingen: licht of DMX passend bij het aftellen, een stream-overlay, een teller bij de ingang – of een Stream Deck als afstandsbediening voor de box.

Systeem → Automatisering: realtime-export, webhooks en lokale API
Systeem → Automatisering: realtime-export, webhooks en lokale API

Webhooks instellen

Vul een Adres (URL) in, onder Windows ook een Programma – of allebei. Bij elke gebeurtenis roept de box alles aan wat is ingevuld:

  • Programma (alleen Windows) – een .exe, .bat of .cmd. Aanroep: programma <gebeurtenis> <param1> <param2> …. Elke waarde komt als apart argument aan, ook als er spaties in staan. Het programma start zonder venster, in zijn eigen map. Een PowerShell-script (.ps1) start je via een kleine .bat ervoor.
  • Adres (URL) – http of https, aangeroepen via GET: https://jouw-server/hook?event_type=<gebeurtenis>&param1=…&param2=…. De waarden zijn URL-gecodeerd; parameters die al in je adres staan, blijven behouden.

Op iPad, iPhone en Mac is er alleen het adres. Daar werkt http:// alleen binnen het lokale netwerk (IP-adres of .local) – Shelly, WLED en Tasmota op de wifi werken dus. Adressen op internet hebben https:// nodig.

De sessie wacht nooit op je webhook: programma en aanroep lopen op de achtergrond, een aanroep mag hooguit 5 seconden duren. Test versturen stuurt meteen een session_start – zo controleer je de verbinding zonder een sessie te starten.

Programma en adres zijn alleen direct op de box in te stellen, niet via de Hub: een programmapad is een recht om iets op de computer uit te voeren.

Eigen adres per gebeurtenis

Vanaf versie 1.5.10 kun je onder Eigen adres per gebeurtenis (optioneel) elke gebeurtenis daarnaast een eigen adres geven – bijvoorbeeld voor een Shelly-stekker, WLED of Tasmota op de wifi die schakelt bij het aftellen of bij de opname. Voorbeeld voor countdown_start: http://192.168.1.50/relay/0?turn=on.

De box roept dit adres aan naast het programma en het adres hierboven, als eenvoudige GET zonder toegevoegde waarden. Het bestaande adres en bestaande scripts blijven ongewijzigd werken. countdown komt elke seconde; bij file_upload roept de box het eigen adres één keer per sessie aan (het algemene adres nog steeds per bestand).

Gebeurtenissen

GebeurtenisWanneerParameters
session_startEen gast start een sessie, de modus staat vast1: modus (PrintOnly, PrintAndGIF, OnlyGIF, SlowMoOr360, Video), 2: BoothDock-modus (photo, gif, boomerang, video, slowmo, ai)
countdown_startHet aftellen begint1: seconden
countdownElke seconde van het aftellen1: voortgang in procent (vanaf 0)
capture_startHet aftellen is voorbij, de opname begint–
file_downloadDe camera heeft een foto opgeslagen1: bestandsnaam, 2: volledig pad
processing_startDe verwerking begintper camera-origineel een bestandsnaam, als laatste waarde het printbestand (momenteel leeg)
sharing_screenHet resultaatscherm verschijnt (eenmaal per sessie)–
printingEen vel gaat naar een printer1: bestand (momenteel leeg), 2: exemplaren, 3: printer
file_uploadEen bestand is in de Hub aangekomen (per bestand)1: pad op de box, 2: galerijlink, 3: type (print, photo, original, animation, boomerang, video), 4: album (naam van het evenement)
lead_submittedEen gast heeft het formulier Gastgegevens (formulier) verstuurd (vanaf 1.5.0)– (de antwoorden zelf staan alleen in de CSV-export)
session_endDe sessie eindigt – voltooid, afgebroken, verlopen of verwijderd–

Voorbeeld van een .bat die elke gebeurtenis bijhoudt: echo %DATE% %TIME% %* >> "%~dp0gebeurtenissen.log"

Lokale API

Andere programma's sturen de box aan via HTTP – bijvoorbeeld een Stream Deck, een eigen script of een 360°-besturing op de telefoon.

  • Inschakelen: Systeem → Automatisering → API inschakelen. Standaard staat de API uit. Poort 1500, aanpasbaar.
  • Adres: http://localhost:1500/api/<opdracht> (of 127.0.0.1). Standaard accepteert de box alleen verzoeken van deze computer.
  • Wachtwoord: 16 tekens, getoond in hetzelfde onderdeel – kopiëren of opnieuw genereren. Meegeven als ?password=…, als header X-Api-Password of als Authorization: Bearer …. Alleen ping werkt zonder.
  • Antwoord: altijd HTTP 200 met JSON, bijvoorbeeld {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Of het gelukt is, staat in IsSuccessful, de reden bij een fout in ErrorMessage. Sommige opdrachten leveren daarnaast Data.

Een volledige aanroep: http://localhost:1500/api/start?mode=print&password=JOUW-WACHTWOORD

Vanuit het netwerk aansturen (telefoon, tablet, 360°)

Schakel daarnaast Ook bereikbaar vanuit het netwerk in. Dan accepteert de box verzoeken van apparaten in hetzelfde wifi-netwerk/LAN – nooit vanaf internet.

  • Adres voor de telefoon: staat in de statusregel, bijvoorbeeld http://192.168.1.20:1500. Het voorbeeld eronder toont dan meteen het juiste adres.
  • Zonder IP in te typen: de box meldt zich zelf aan op het netwerk (mDNS/Bonjour, diensttype _boothdock._tcp, naam „BoothDock" plus computernaam). Apps die daarnaar zoeken, vinden hem automatisch.
  • Blokkering: stuurt een apparaat binnen tien minuten tien keer een verkeerd wachtwoord, dan wordt het 15 minuten geblokkeerd. Deze computer zelf wordt nooit geblokkeerd.
  • Alleen in je eigen netwerk: het wachtwoord gaat onversleuteld over het netwerk. Gebruik de netwerkmodus alleen in je eigen, beveiligde wifi – niet in het open gastennetwerk van de locatie.
  • Firewall: de installatie stelt de toegang in, alleen voor privénetwerken. Toont de statusregel een firewallwaarschuwing, installeer BoothDock Studio dan opnieuw of sta het in Windows toe onder „Een app toestaan via firewall". Behandelt Windows de wifi als openbaar, dan komen apparaten er niet in – zet het profiel in de netwerkeigenschappen op Privé.

Opdrachten

OpdrachtEffect
start?mode=printStart een sessie. Modi: print (foto), gif, boomerang, slowmo (360°; zonder 360° de boomerang), video, ai. Werkt alleen vanaf het startscherm, alleen met een ingeschakelde modus en niet als de box vergrendeld is. Met sjabloon, stijl en achtergrond: zie hieronder.
auswahl?mode=printLevert in Data wat er voor deze modus te kiezen valt: vorlagen (Id en naam; leeg als er maar één sjabloon is vrijgegeven – die staat dan in vorgabeVorlage), hintergruende per sjabloon en in de modus ai de stile (vanaf 1.5.13).
cancelBreekt de lopende sessie af en gaat terug naar het startscherm.
statusLevert in Data: gastmodus aan/uit, huidig scherm, modus, vergrendeld ja/nee – vanaf 1.5.13 ook sperrgrund (manuell of zeitfenster) en oeffnetUm.
print?count=1Drukt het laatste resultaat nog een keer af (1 tot 10 vellen). Video's kunnen niet worden afgedrukt.
lockscreen/showVergrendelt de box met „Een moment – we gaan zo verder." of met je eigen tekst en afbeelding (zie „Vergrendelscherm” hieronder). De beheerhoek blijft bereikbaar. Vanaf 1.5.13 blijft de vergrendeling ook na een herstart van de app bestaan.
lockscreen/exitHeft de vergrendeling op – vanaf 1.5.13 ook de vergrendeling door het tijdvenster, tot de volgende wissel.
share/email?email=…Stuurt het laatste resultaat per e-mail – vereist de koppeling met de Hub en de resultaatactie „Per e-mail ontvangen” (Systeem → Werking → Resultaatacties (gast); t/m 1.4.0 de schakelaar „Foto per e-mail (gast)” onder Ontwerp → Schermen).
share/smsBestaat niet; het antwoord zegt dat eerlijk (IsSuccessful: false).
createtestevent?name=…Maakt een testevenement aan en maakt het actief. Data bevat eventId en eventName. Zonder naam krijgt het er een met datum. Alleen buiten de gastmodus (vanaf 1.5.4).
deletetestevent?eventId=…Verwijdert een testevenement dat via de API is aangemaakt – nooit andere evenementen. Alleen buiten de gastmodus (vanaf 1.5.4).
pingControleert zonder wachtwoord of de API draait.

Antwoordt de box niet binnen 15 seconden, dan komt IsSuccessful: false met een toelichting terug.

Sessie starten met sjabloon, stijl en achtergrond

Vanaf versie 1.5.13 neemt start de keuze meteen mee – de box slaat dan precies deze keuzeschermen over:

  • vorlage=<Id> (of template=) – het sjabloon, alleen in de modus print (foto). De Id's levert auswahl?mode=print.
  • stil=<Id> (of style=) – de AI-stijl, alleen in de modus ai.
  • hintergrund=<Id> (of background=) – de achtergrond voor het uitknippen, passend bij het sjabloon.

Voorbeeld: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=JOUW-WACHTWOORD

Een onbekende of niet-passende Id start geen sessie: IsSuccessful is false, ErrorMessage noemt de reden. De privacytoestemming en het formulier voor gastgegevens toont de box nog steeds zelf – die gelden voor de gast vóór de box en kunnen niet vooraf via de API worden afgehandeld.

Vergrendelscherm

Onder Evenementen → Vergrendelscherm (vanaf 1.5.13) leg je vast wat een vergrendelde box toont: eigen tekst, een eigen afbeelding en – bij het tijdvenster – een grote aftelling tot de opening.

  • Tijdvenster per evenement: Met Opent om en Sluit om is de box vóór de start en na het einde vergrendeld.
  • Ontgrendelen op het apparaat: Is er een beheerderspincode ingesteld (Systeem → Beveiliging), dan toont het vergrendelscherm een klein slotje. Wie de pincode kent, ontgrendelt de box. Vóór de start vrijgegeven, blijft hij open tot het einde.
  • Op afstand: In de Hub vergrendel en ontgrendel je onder Booths elke box die dat ondersteunt (Studio vanaf 1.5.13). Hetzelfde kan via BoothDock Station en met lockscreen/show / lockscreen/exit.

Een lopende sessie wordt niet afgebroken door de vergrendeling vanuit de Hub of door het tijdvenster – de box vergrendelt zodra de gast klaar is.

Realtime-export

In hetzelfde tabblad: elk afgerond bestand komt meteen op de box zelf terecht (Lokale kopie) – ook zonder Hub, gesorteerd op evenement en type (afdrukken, originelen, GIF's, video's – elk apart uit te schakelen). Deze kopie wordt nooit automatisch verwijderd. Onder USB-stick / tweede map voeg je een tweede doel toe: Automatisch naar USB-stick schrijven schrijft naar elke geplaatste stick, Gemiste bestanden inhalen schrijft achteraf weg wat zonder stick is ontstaan. Je kunt ook een Vaste tweede map (heeft voorrang) opgeven, bijvoorbeeld een cloudmap (OneDrive, Dropbox). Verwijdert een gast zijn sessie op de box, dan verdwijnen ook de kopieën. Op iPad en iPhone: In de Bestanden-app onder ‘Op mijn iPad › BoothDock Studio › Export’. In BoothDock Studio 1.5.3 en ouder is er in plaats daarvan alleen de Exportmap.

Starten met afstandsbediening

In hetzelfde tabblad leer je onder Starten met afstandsbediening een toets in. Presenters, USB-knoppen en voetschakelaars sturen meestal de spatiebalk; die is vooringesteld. Bij Start kies je wat de toets op het startscherm doet: Zoals aanraken (normale flow) of meteen een modus, bijvoorbeeld 360° op het platform. In BoothDock Studio 1.4.0 en ouder bestaat de toets alleen voor 360°, zie 360° / slow motion.

Probleemoplossing

  • Er gebeurt niets: staat er iets in het logboek? Webhooks schrijven naar webhooks.log (t/m 1.4.0: ausloeser.log), de API naar lokale-api.log – beide in de map %LocalAppData%\Boothdock Studio\logs (Windows). Geweigerde verzoeken (verkeerd wachtwoord, onbekend apparaat) staan daar hooguit één keer per minuut.
  • „Invalid password." – wachtwoord opnieuw kopiëren; na Nieuw wachtwoord is het oude niet meer geldig.
  • „The booth is not on the start screen …" – start werkt alleen vanaf het startscherm. Eerst cancel, dan start.
  • „Too many failed attempts …" – het apparaat heeft te vaak een verkeerd wachtwoord gestuurd. 15 minuten wachten, wachtwoord controleren.
  • Telefoon bereikt de box niet, op de computer werkt alles: bijna altijd de Windows Firewall of een wifi-netwerk dat als openbaar wordt behandeld – zie hierboven. Beide gevallen meldt de statusregel.

Volgende stappen