EliteG19s Webhook Guide

Use the webhook service to trigger any IRemoteControl command from simple HTTP requests. This guide expands on the summary in the main manual and walks through setup, payload formats, and tooling examples using curl, PowerShell, and Postman.

1. Enable the Webhook Listener

1. Open %AppData%\EliteG19s\options.json.
2. Locate the "Webhooks" section (create it if absent):

   {
     "Webhooks": {
       "IsEnabled": true,
       "Port": 32123
     }
   }
   

   • IsEnabled: turns the listener on or off (default false).
   • Port: TCP port for incoming requests (default 32123).
3. Save the file and restart EliteG19s. On startup the app binds to http://localhost:<port>/.

Note: The listener currently binds to localhost only. To expose it outside the machine, use an HTTP reverse proxy or tunnelling tool and secure the connection yourself.

2. Endpoints and Payloads

2.1 Request Format

Send JSON with at least a command property. Additional properties become command parameters. You may also nest them under parameters.

{
  "command": "SwitchScreen",
  "screenName": "Status"
}

2.2 Response Format

Successful responses:

{
  "success": true,
  "command": "SwitchScreen",
  "result": null
}

Errors return HTTP 4xx/5xx and:

{
  "success": false,
  "error": "Unknown command 'Foo'"
}

3. Command Catalogue

Every webhook command maps 1:1 to an IRemoteControl method. The tables below list every handler, the payload properties it understands, plus important value ranges. Unless stated otherwise commands return success: true with a null result.

3.1 Audio Output

3.2 Playback Transport

3.3 Audio Sources

3.4 Screen Control and Visualizations

3.5 Space Traffic Control and NPC Voices

3.6 Logitech Button Simulation and Interactive Prompts

3.7 Navigation, Orrery, and Waypoints

3.8 Shopping List and Commodity Search

3.9 Status Queries

3.10 Messaging and Logging

Boolean parameters accept JSON true/false or 1/0. String comparisons ignore letter case unless noted. When a payload omits an optional property the handler falls back to safe defaults.

4. Working with curl

4.1 Windows PowerShell (curl.exe)

curl.exe http://localhost:32123/remote-control ^
  -H "Content-Type: application/json" ^
  -d "{\"command\":\"ChangeVolume\",\"delta\":15}"

4.2 Windows PowerShell (Invoke-RestMethod)

Invoke-RestMethod `
  -Uri http://localhost:32123/remote-control `
  -Method Post `
  -ContentType application/json `
  -Body (@{ command = "SwitchScreen"; screenName = "Status" } | ConvertTo-Json)

4.3 macOS / Linux curl

curl http://localhost:32123/remote-control \
  -H "Content-Type: application/json" \
  -d '{"command":"GetStatus"}'

5. Using Postman

1. Create a new POST request with URL http://localhost:32123/remote-control.
2. In the Body tab choose raw and JSON.
3. Paste the payload, for example:

   {
     "command": "ListenToRadiostation",
     "name": "Radio Sidewinder"
   }
   

4. Send the request and inspect the JSON response in the lower panel.
5. Save the request in a Postman collection if you want reusable automations.

6. Status Checks and Logging

• Health check: GET http://localhost:32123/health returns { "status": "ok" } when the listener is running.
• Application log: The main log (%AppData%\EliteG19s\log.txt when logging is enabled) records listener start, stop, and any command execution failures.
• Trace on failure: If a command returns an internal server error, check log.txt for the underlying exception message.

7. Troubleshooting

8. Automation Platform Samples

8.1 Windows Task Scheduler (PowerShell)

Use a scheduled PowerShell script that posts JSON with Invoke-RestMethod. Below shows two ready-to-save snippets.

# Morning volume boost at 07:30
Invoke-RestMethod -Uri http://localhost:32123/remote-control -Method Post -ContentType application/json -Body (
  @{ command = "ChangeVolume"; delta = 15 } | ConvertTo-Json
)

# Shift the display to Status screen before play sessions
Invoke-RestMethod -Uri http://localhost:32123/remote-control -Method Post -ContentType application/json -Body (
  @{ command = "SwitchScreen"; screen = "Status" } | ConvertTo-Json
)

Assign each script to a basic task and run powershell.exe -File c:\Path\To\Script.ps1 as the scheduled action.

8.2 Node-RED Flow (HTTP Request Node)

Import the following flow to trigger webhook calls from inject buttons. Each inject node sends one JSON payload to /remote-control.

[
  {
    "id": "flow-root",
    "type": "tab",
    "label": "EliteG19s Webhooks"
  },
  {
    "id": "inject-volume",
    "type": "inject",
    "z": "flow-root",
    "name": "Volume +10",
    "props": [{ "p": "payload" }],
    "payload": "{\"command\":\"ChangeVolume\",\"delta\":10}",
    "payloadType": "json",
    "repeat": "",
    "once": false,
    "wires": [["http-elite"]]
  },
  {
    "id": "inject-spotify",
    "type": "inject",
    "z": "flow-root",
    "name": "Play Spotify Preset",
    "props": [{ "p": "payload" }],
    "payload": "{\"command\":\"ListenToSpotifyPlaylist\",\"playlist\":\"Morning Mix\"}",
    "payloadType": "json",
    "wires": [["http-elite"]]
  },
  {
    "id": "http-elite",
    "type": "http request",
    "z": "flow-root",
    "name": "EliteG19s Webhook",
    "method": "POST",
    "ret": "obj",
    "url": "http://localhost:32123/remote-control",
    "headers": [{ "key": "Content-Type", "value": "application/json" }]
  }
]

Deploy the flow, then click the inject buttons to test.

8.3 Home Assistant Automations (REST Commands)

Define reusable REST commands in configuration.yaml, then call them from automations.

rest_command:
  eliteg19s_switch_screen:
    url: "http://localhost:32123/remote-control"
    method: post
    headers:
      Content-Type: application/json
    payload: '{"command":"SwitchScreen","screen":"Orrery"}'

  eliteg19s_radiostation:
    url: "http://localhost:32123/remote-control"
    method: post
    headers:
      Content-Type: application/json
    payload: '{"command":"ListenToRadiostation","station":"Radio Sidewinder"}'

automation:
  - alias: "Daily Orrery Overview"
    trigger:
      - platform: time
        at: "20:00:00"
    action:
      - service: rest_command.eliteg19s_switch_screen

  - alias: "Start Evening Radio"
    trigger:
      - platform: state
        entity_id: person.commander
        to: home
    action:
      - service: rest_command.eliteg19s_radiostation

Reload Home Assistant commands and automations, then use any trigger (time or presence) to dispatch the payloads.

9. Next Steps

• Combine webhook calls with Windows Task Scheduler, cron, or automation platforms like Node-RED and Home Assistant webhooks.
• Mix-and-match with MQTT: MQTT for publish-subscribe automations, webhooks for on-demand actions.
• Consider scripting wrappers (PowerShell modules, shell scripts) that encapsulate common payloads for your setup.