Webhooks und API - BoothDock Wiki

BoothDock Studio kann andere Programme über jeden Schritt einer Sitzung informieren (Webhooks) und sich selbst von anderen Programmen steuern lassen (lokale API). Beides findest du im Admin-Bereich unter System → Automatisierung.

In BoothDock Studio 1.4.0 und älter heißen die Webhooks dort noch „Auslöser“.

Webhooks und Echtzeit-Export gibt es nur unter Windows. Die lokale API gibt es ab Version 1.4.0 auch auf iPad und iPhone.

Typische Anwendungen: Licht oder DMX passend zum Countdown, ein Stream-Overlay, ein Zähler am Eingang – oder ein Stream Deck als Fernbedienung für die Box.

System → Automatisierung: Echtzeit-Export, Webhooks und lokale API

Webhooks einrichten

Trag ein Programm, eine Adresse (URL) oder beides ein. Bei jedem Ereignis ruft die Box beides auf:

Programm – eine .exe, .bat oder .cmd. Aufruf: programm <ereignis> <param1> <param2> …. Jeder Wert kommt als eigenes Argument an, auch wenn er Leerzeichen enthält. Das Programm startet ohne Fenster, im eigenen Ordner. Ein PowerShell-Skript (.ps1) startest du über eine kleine .bat davor.
Adresse (URL) – http oder https, aufgerufen per GET: https://dein-server/hook?event_type=<ereignis>&param1=…&param2=…. Die Werte sind URL-kodiert; Parameter, die schon in deiner Adresse stehen, bleiben erhalten.

Die Sitzung wartet nie auf deinen Webhook: Programm und Aufruf laufen nebenher, ein Aufruf darf höchstens 5 Sekunden dauern. Probe senden schickt sofort ein session_start – so prüfst du die Verbindung, ohne eine Sitzung zu starten.

Programm und Adresse lassen sich nur direkt an der Box einstellen, nicht über den Hub: Ein Programmpfad ist ein Recht, etwas auf dem Rechner auszuführen.

Ereignisse

Ereignis	Wann	Parameter
`session_start`	Ein Gast startet eine Sitzung, der Modus steht fest	1: Modus (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2: BoothDock-Modus (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Der Countdown beginnt	1: Sekunden
`countdown`	Jede Sekunde des Countdowns	1: Fortschritt in Prozent (ab 0)
`capture_start`	Der Countdown ist durch, die Aufnahme beginnt	–
`file_download`	Die Kamera hat ein Foto abgelegt	1: Dateiname, 2: vollständiger Pfad
`processing_start`	Die Bearbeitung beginnt	je Kamera-Original ein Dateiname, als letzter Wert die Druckdatei (derzeit leer)
`sharing_screen`	Der Ergebnisbildschirm erscheint (einmal je Sitzung)	–
`printing`	Ein Blatt geht an einen Drucker	1: Datei (derzeit leer), 2: Kopien, 3: Drucker
`file_upload`	Eine Datei ist im Hub angekommen (je Datei)	1: Pfad auf der Box, 2: Galerie-Link, 3: Typ (`print`, `photo`, `original`, `animation`, `boomerang`, `video`), 4: Album (Eventname)
`session_end`	Die Sitzung endet – fertig, abgebrochen, abgelaufen oder gelöscht	–

Beispiel für eine .bat, die jedes Ereignis mitschreibt: echo %DATE% %TIME% %* >> "%~dp0ereignisse.log"

Lokale API

Andere Programme steuern die Box per HTTP – etwa ein Stream Deck, ein eigenes Skript oder eine 360°-Steuerung auf dem Handy.

Einschalten: System → Automatisierung → API einschalten. Ab Werk ist die API aus. Port 1500, änderbar.
Adresse: http://localhost:1500/api/<befehl> (oder 127.0.0.1). Ab Werk nimmt die Box nur Anfragen von diesem Rechner an.
Passwort: 16 Zeichen, angezeigt im selben Abschnitt – kopieren oder neu erzeugen. Mitgeben als ?password=…, als Kopfzeile X-Api-Password oder als Authorization: Bearer …. Nur ping geht ohne.
Antwort: immer HTTP 200 mit JSON, zum Beispiel {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Ob es geklappt hat, steht in IsSuccessful, der Grund im Fehlerfall in ErrorMessage. Einige Befehle liefern zusätzlich Data.

Ein vollständiger Aufruf: http://localhost:1500/api/start?mode=print&password=DEIN-PASSWORT

Aus dem Netz steuern (Handy, Tablet, 360°)

Schalte zusätzlich Auch aus dem Netzwerk erreichbar ein. Dann nimmt die Box Anfragen von Geräten im selben WLAN/LAN an – nie aus dem Internet.

Adresse fürs Handy: steht in der Statuszeile, zum Beispiel http://192.168.1.20:1500. Das Beispiel darunter zeigt dann gleich die passende Adresse.
Ohne IP-Eingabe: Die Box meldet sich im Netz selbst an (mDNS/Bonjour, Diensttyp _boothdock._tcp, Name „BoothDock" plus Rechnername). Apps, die danach suchen, finden sie automatisch.
Sperre: Schickt ein Gerät zehnmal in zehn Minuten ein falsches Passwort, ist es 15 Minuten gesperrt. Dieser Rechner selbst wird nie gesperrt.
Nur im eigenen Netz: Das Passwort geht unverschlüsselt durchs Netz. Nutze den Netzbetrieb nur in deinem eigenen, geschützten WLAN – nicht im offenen Gäste-WLAN der Location.
Firewall: Die Installation richtet die Freigabe ein, nur für private Netzwerke. Zeigt die Statuszeile eine Firewall-Warnung, installiere BoothDock Studio erneut oder erlaube es in Windows unter „App durch die Firewall zulassen". Führt Windows das WLAN als öffentlich, kommen Geräte nicht herein – stell das Profil in den Netzwerkeigenschaften auf Privat.

Befehle

Befehl	Wirkung
`start?mode=print`	Startet eine Sitzung. Modi: `print` (Foto), `gif`, `boomerang`, `slowmo` (360°; ohne 360° der Boomerang), `video`, `ai`. Geht nur vom Startbildschirm aus, nur mit freigeschaltetem Modus und nicht bei gesperrter Box.
`cancel`	Bricht die laufende Sitzung ab und geht zurück zum Startbildschirm.
`status`	Liefert in `Data`: Gastmodus an/aus, aktueller Bildschirm, Modus, gesperrt ja/nein.
`print?count=1`	Druckt das letzte Ergebnis noch einmal (1 bis 10 Blätter). Videos lassen sich nicht drucken.
`lockscreen/show`	Sperrt die Box mit „Einen Moment – gleich geht's weiter." Die Admin-Ecke bleibt erreichbar.
`lockscreen/exit`	Hebt die Sperre auf.
`share/email?email=…`	Schickt das letzte Ergebnis per E-Mail – braucht die Hub-Kopplung und die Ergebnis-Aktion „Per E-Mail erhalten“ (System → Betrieb → Ergebnis-Aktionen (Gast); bis 1.4.0 der Schalter „Foto per E-Mail (Gast)“ unter Design → Screens).
`share/sms`	Gibt es nicht; die Antwort sagt das ehrlich (`IsSuccessful: false`).
`createtestevent?name=…`	Legt ein Testevent an und macht es aktiv. `Data` enthält `eventId` und `eventName`. Ohne Namen gibt es einen mit Datum.
`deletetestevent?eventId=…`	Löscht ein Testevent, das über die API angelegt wurde – andere Events nie.
`ping`	Prüft ohne Passwort, ob die API läuft.

Antwortet die Box nicht innerhalb von 15 Sekunden, kommt IsSuccessful: false mit einem Hinweis zurück.

Echtzeit-Export

Im selben Reiter wählst du einen Exportordner – etwa einen USB-Stick oder einen Cloud-Ordner (OneDrive, Dropbox). Jede fertige Datei landet dort sofort, sortiert nach Event und Typ (Drucke, Originale, GIFs, Videos – einzeln abschaltbar). Fehlt der Stick kurz, holt die Box die Dateien nach. Löscht ein Gast seine Sitzung am Automaten, verschwinden auch die Kopien.

Start per Fernbedienung

Im selben Reiter lernst du unter Start per Fernbedienung eine Taste an. Presenter, USB-Taster und Fußschalter senden meist die Leertaste; die ist voreingestellt. Bei Startet wählst du, was die Taste am Startbildschirm auslöst: Wie Berühren (normaler Ablauf) oder gleich einen Modus, zum Beispiel 360° an der Plattform. In BoothDock Studio 1.4.0 und älter gibt es die Taste nur für 360°, siehe 360° / Zeitlupe.

Fehlersuche

Nichts passiert: Steht im Protokoll etwas? Webhooks schreiben nach webhooks.log (bis 1.4.0: ausloeser.log), die API nach lokale-api.log – beide im Ordner %LocalAppData%\Boothdock Studio\logs. Abgelehnte Anfragen (falsches Passwort, fremdes Gerät) stehen dort höchstens einmal pro Minute.
„Invalid password." – Passwort neu kopieren; nach Neues Passwort gilt das alte nicht mehr.
„The booth is not on the start screen …" – start geht nur vom Startbildschirm. Erst cancel, dann start.
„Too many failed attempts …" – das Gerät hat zu oft ein falsches Passwort geschickt. 15 Minuten warten, Passwort prüfen.
Handy erreicht die Box nicht, am Rechner geht alles: fast immer die Windows-Firewall oder ein als öffentlich geführtes WLAN – siehe oben. Beide Fälle meldet die Statuszeile.