← All articles

BoothDock · Wiki

Webhooks and API

BoothDock Studio can notify other programs about every step of a session (Webhooks) and can itself be controlled by other programs (local API). You'll find both in the admin area under System → Automation.

In BoothDock Studio 1.4.0 and earlier, the webhooks section there is still called “Triggers”.

Webhooks are available on Windows and, from version 1.5.10, also on iPad, iPhone and Mac. The local API is also available on iPad, iPhone and Mac from version 1.4.0, real-time export from version 1.5.2.

Typical uses: lights or DMX in sync with the countdown, a stream overlay, a counter at the entrance – or a Stream Deck as a remote control for the box.

System → Automation: real-time export, webhooks and local API
System → Automation: real-time export, webhooks and local API

Setting up webhooks

Enter an Address (URL), on Windows also a Program – or both. On every event the box calls everything you've entered:

  • Program (Windows only) – an .exe, .bat or .cmd. Call: program <event> <param1> <param2> …. Each value arrives as a separate argument, even if it contains spaces. The program starts without a window, in its own folder. To run a PowerShell script (.ps1), put a small .bat in front of it.
  • Address (URL) – http or https, called via GET: https://your-server/hook?event_type=<event>&param1=…&param2=…. The values are URL-encoded; parameters that are already part of your address are kept.

On iPad, iPhone and Mac there is only the address. There, http:// only works within the local network (IP address or .local) – so Shelly, WLED and Tasmota on your Wi-Fi work. Addresses on the internet need https://.

The session never waits for your webhook: the program and the call run alongside it, and a call may take at most 5 seconds. Send test immediately sends a session_start – that way you can check the connection without starting a session.

Program and address can only be set directly on the box, not via the Hub: a program path is the right to run something on the computer.

Separate address per event

From version 1.5.10, under Separate address per event (optional) you can additionally give each event its own address – for example for a Shelly plug, WLED or Tasmota on your Wi-Fi that switches at the countdown or at capture. Example for countdown_start: http://192.168.1.50/relay/0?turn=on.

The box calls this address in addition to the program and address above, as a plain GET without any added values. Your previous address and existing scripts keep working unchanged. countdown arrives every second; for file_upload the box calls its own address once per session (the general address still once per file).

Events

EventWhenParameters
session_startA guest starts a session, the mode is set1: mode (PrintOnly, PrintAndGIF, OnlyGIF, SlowMoOr360, Video), 2: BoothDock mode (photo, gif, boomerang, video, slowmo, ai)
countdown_startThe countdown begins1: seconds
countdownEvery second of the countdown1: progress in percent (from 0)
capture_startThe countdown is over, the capture begins–
file_downloadThe camera has saved a photo1: file name, 2: full path
processing_startProcessing beginsone file name per camera original, the print file as the last value (currently empty)
sharing_screenThe result screen appears (once per session)–
printingA sheet is sent to a printer1: file (currently empty), 2: copies, 3: printer
file_uploadA file has arrived in the Hub (per file)1: path on the box, 2: gallery link, 3: type (print, photo, original, animation, boomerang, video), 4: album (event name)
lead_submittedA guest has submitted the Guest data (form) form (from 1.5.0)– (the answers themselves are only in the CSV export)
session_endThe session ends – finished, cancelled, timed out or deleted–

Example of a .bat that logs every event: echo %DATE% %TIME% %* >> "%~dp0events.log"

Local API

Other programs control the box via HTTP – for example a Stream Deck, your own script or a 360° controller on a phone.

  • Turning it on: System → Automation → Enable API. The API is off by default. Port 1500, can be changed.
  • Address: http://localhost:1500/api/<command> (or 127.0.0.1). By default the box only accepts requests from this computer.
  • Password: 16 characters, shown in the same section – copy it or generate a new one. Pass it as ?password=…, as the X-Api-Password header or as Authorization: Bearer …. Only ping works without it.
  • Response: always HTTP 200 with JSON, for example {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Whether it worked is shown in IsSuccessful; if it failed, the reason is in ErrorMessage. Some commands also return Data.

A complete call: http://localhost:1500/api/start?mode=print&password=YOUR-PASSWORD

Controlling from the network (phone, tablet, 360°)

Also turn on Also reachable from the network. The box then accepts requests from devices on the same Wi-Fi/LAN – never from the internet.

  • Address for the phone: shown in the status line, for example http://192.168.1.20:1500. The example below it then shows the matching address right away.
  • Without entering an IP: The box announces itself on the network (mDNS/Bonjour, service type _boothdock._tcp, name "BoothDock" plus the computer name). Apps that look for it find it automatically.
  • Lockout: If a device sends a wrong password ten times within ten minutes, it is locked out for 15 minutes. This computer itself is never locked out.
  • Only on your own network: The password travels across the network unencrypted. Use network mode only on your own, protected Wi-Fi – not on the venue's open guest Wi-Fi.
  • Firewall: The installer sets up the rule, for private networks only. If the status line shows a firewall warning, reinstall BoothDock Studio or allow it in Windows under "Allow an app through firewall". If Windows treats the Wi-Fi as public, devices can't get in – set the profile to Private in the network properties.

Commands

CommandEffect
start?mode=printStarts a session. Modes: print (photo), gif, boomerang, slowmo (360°; without 360°, boomerang), video, ai. Only works from the start screen, only with an enabled mode and not while the box is locked. With template, style and background: see below.
auswahl?mode=printReturns in Data what there is to choose for this mode: vorlagen (Id and name; empty if only one template is enabled – it is then in vorgabeVorlage), hintergruende per template and, in ai mode, the stile (from 1.5.13).
cancelCancels the current session and returns to the start screen.
statusReturns in Data: guest mode on/off, current screen, mode, locked yes/no – from 1.5.13 also sperrgrund (manuell or zeitfenster) and oeffnetUm.
print?count=1Prints the last result again (1 to 10 sheets). Videos can't be printed.
lockscreen/showLocks the box with "One moment – we'll be right back." or your own text and image (see "Lock screen" below). The admin corner stays reachable. From 1.5.13 the lock also survives a restart of the app.
lockscreen/exitLifts the lock – from 1.5.13 also the time-window lock, until the next change.
share/email?email=…Sends the last result by email – requires Hub pairing and the “Get by email” result action (System → Operation → Result actions (guest); up to 1.4.0 the “Photo by email (guest)” switch under Design → Screens).
share/smsDoesn't exist; the response says so honestly (IsSuccessful: false).
createtestevent?name=…Creates a test event and makes it active. Data contains eventId and eventName. Without a name you get one with the date. Only outside guest mode (from 1.5.4).
deletetestevent?eventId=…Deletes a test event that was created via the API – never other events. Only outside guest mode (from 1.5.4).
pingChecks without a password whether the API is running.

If the box doesn't respond within 15 seconds, IsSuccessful: false comes back with a note.

Starting a session with template, style and background

From version 1.5.13, start takes the choice right away – the box then skips exactly these selection screens:

  • vorlage=<Id> (or template=) – the template, only in print mode (photo). auswahl?mode=print returns the Ids.
  • stil=<Id> (or style=) – the AI style, only in ai mode.
  • hintergrund=<Id> (or background=) – the background for the cut-out, matching the template.

Example: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=YOUR-PASSWORD

An unknown or non-matching Id starts no session: IsSuccessful is false, ErrorMessage names the reason. The box still shows the privacy consent and the guest data form itself – they apply to the guest in front of the box and cannot be done in advance via the API.

Lock screen

Under Events → Lock screen (from 1.5.13) you set what a locked box shows: your own text, your own image and – with the time window – a large countdown to opening.

  • Time window per event: With Opens at and Closes at, the box is locked before the start and after the end.
  • Unlock on the device: If an operator PIN is set up (System → Protection), the lock screen shows a small padlock. Anyone who knows the PIN unlocks the box. Unlocked before the start, it stays open until the end.
  • Remotely: In the Hub under Boxes you lock and unlock every box that supports it (Studio from 1.5.13). The same works via BoothDock Station and with lockscreen/show / lockscreen/exit.

Neither the lock from the Hub nor the time window interrupts a running session – the box locks as soon as the guest is done.

Real-time export

In the same tab: every finished file lands immediately on the box itself (Local copy) – even without the Hub, sorted by event and type (prints, originals, GIFs, videos – each can be switched off). This copy is never deleted automatically. Under USB drive / second folder you add a second destination: Write to USB drive automatically writes to every inserted stick, Catch up on missed files writes whatever was created without a stick. Alternatively, enter a Fixed second folder (takes precedence), such as a cloud folder (OneDrive, Dropbox). If a guest deletes their session at the booth, the copies disappear too. On iPad and iPhone: In the Files app under “On My iPad › BoothDock Studio › Export”. In BoothDock Studio 1.5.3 and older there is only the Export folder instead.

Start by remote

In the same tab you learn a key under Start by remote. Presenters, USB buttons and foot switches usually send the space bar; that is preset. Under Starts you choose what the key does on the start screen: Like touching (normal flow) or a mode straight away, for example 360° on the platform. In BoothDock Studio 1.4.0 and earlier the key exists only for 360°, see 360° / Slow motion.

Troubleshooting

  • Nothing happens: Is there anything in the log? Webhooks write to webhooks.log (up to 1.4.0: ausloeser.log), the API to lokale-api.log – both in the folder %LocalAppData%\Boothdock Studio\logs (Windows). Rejected requests (wrong password, unknown device) are logged there at most once per minute.
  • "Invalid password." – copy the password again; after New password the old one is no longer valid.
  • "The booth is not on the start screen …" – start only works from the start screen. First cancel, then start.
  • "Too many failed attempts …" – the device sent a wrong password too often. Wait 15 minutes, check the password.
  • The phone can't reach the box, but everything works on the computer: almost always the Windows Firewall or a Wi-Fi network treated as public – see above. The status line reports both cases.

Next steps