help Help

IoT API Reference

Complete API documentation for IoT integration
Connect sensors, devices, and external systems to your digital signage

[ SignService API | Webhooks | Event-Driven Architecture ]

API Documentation Contents

SignService API

SignService runs on port 8094 using HTTPS. All requests require the --insecure flag due to self-signed certificates.

Base URL

https://SIGNSERVICE_HOST:8094

Example: https://192.168.68.52:8094

1. Send Event to SignPlayer

Send data to SignPlayer for display or processing.

POST /player/sendEvent?eventName={eventName}&store={0|1}

Parameters

Parameter Type Required Description
eventName string Yes Event identifier (must match SignStudio config)
store integer No 1 = persist event, 0 = transient (default: 0)

Request Body

JSON data to send to SignPlayer.

JSON 
{
  "name": "value",
  "anyField": "anyValue"
}

Example: Send Temperature Data

curl 
curl 'https://192.168.68.52:8094/player/sendEvent?eventName=myCustomEvent&store=1' \
  -X POST \
  -H 'Content-Type: application/json' \
  --data-raw '{"name": "25.3"}' \
  --insecure

Example: Send Complex Data

curl 
curl 'https://192.168.68.52:8094/player/sendEvent?eventName=elevatorStatus&store=1' \
  -X POST \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "floor": 5,
    "direction": "up",
    "doorStatus": "closed",
    "timestamp": "2025-12-26T10:30:00Z"
  }' \
  --insecure

Response

JSON 
{
  "success": true
}

2. Register Event Listener

Register a callback URL to receive events when SignPlayer fires them.

POST /player/registerEvent?eventName={eventName}&callbackUrl={url}

Parameters

Parameter Type Required Description
eventName string Yes Event to listen for
callbackUrl string Yes URL to receive callbacks (URL-encoded)

Example

curl 
curl 'https://192.168.68.52:8094/player/registerEvent?eventName=clickAlarm&callbackUrl=http%3A%2F%2F192.168.68.24%3A5001%2Fcallback' \
  -X POST \
  --insecure
Callback URL Requirements:
  • Must be accessible from the SignService machine
  • Must be URL-encoded in the request
  • Must be ready to receive POST requests

Example decoded URL: http://192.168.68.24:5001/callback

Response

JSON 
{
  "success": true,
  "eventName": "clickAlarm",
  "callbackUrl": "http://192.168.68.24:5001/callback"
}

3. Unregister Event Listener

Remove a previously registered callback.

POST /player/unregisterEvent?eventName={eventName}&callbackUrl={url}

Parameters

Parameter Type Required Description
eventName string Yes Event to unregister from
callbackUrl string Yes URL to remove (URL-encoded)

Example

curl 
curl 'https://192.168.68.52:8094/player/unregisterEvent?eventName=clickAlarm&callbackUrl=http%3A%2F%2F192.168.68.24%3A5001%2Fcallback' \
  -X POST \
  --insecure

Response

JSON 
{
  "success": true
}

4. List Registered Events

Get all currently registered events and their callbacks.

GET /player/registeredEvents

Example

curl 
curl 'https://192.168.68.52:8094/player/registeredEvents' \
  --insecure

Response

JSON 
{
  "events": {
    "clickAlarm": [
      "http://192.168.68.24:5001/callback",
      "http://192.168.68.25:5001/callback"
    ],
    "tempUpdate": [
      "http://192.168.68.24:5002/callback"
    ]
  }
}

Callback Webhook API

When an event is fired by SignPlayer, SignService sends a POST request to all registered callback URLs.

Callback Request

POST {callbackUrl}
Content-Type: application/json

Request Body

JSON 
{
  "eventName": "clickAlarm",
  "timestamp": "2025-12-26T10:30:00.000Z",
  "data": {
    "clickAlarm": "on"
  }
}

Expected Response

Your callback server should respond with:

JSON 
{
  "status": "received"
}
Status Code: Return 200 OK to acknowledge receipt. Any other status code may trigger retries.

IoT Web Portal API

The web portal runs on port 5000 using HTTP.

Base URL

http://localhost:5000

1. Get HTML UI

GET /

Returns the interactive web interface.

2. SSE Event Stream

Real-time event stream using Server-Sent Events.

GET /events

Connect with EventSource:

JavaScript 
const eventSource = new EventSource('/events');
eventSource.onmessage = (e) => {
    const data = JSON.parse(e.data);
    console.log('Received:', data);
};

3. Receive Callback

Endpoint for SignService callbacks.

POST /callback
Content-Type: application/json
JSON Request Body 
{
  "eventName": "clickAlarm",
  "data": {
    "clickAlarm": "on"
  }
}

4. Register Event

Register an event listener through the portal.

POST /register?eventName={eventName}
curl 
curl 'http://localhost:5000/register?eventName=myEvent' \
  -X POST
Response 
{
  "success": true,
  "eventName": "myEvent",
  "callbackUrl": "http://192.168.68.24:5000/callback"
}

5. Unregister Event

Remove an event listener.

POST /unregister?eventName={eventName}

6. Send Event

Send event through the portal to SignPlayer.

POST /send?eventName={eventName}
Content-Type: application/json
JSON Request Body 
{
  "name": "hello"
}

7. Get Registered Events

List events registered through this portal.

GET /registeredEvents
Response 
{
  "events": [
    {
      "eventName": "clickAlarm",
      "callbacks": ["http://192.168.68.24:5000/callback"]
    }
  ]
}

8. Configure SignService Host

Set the SignService IP address.

POST /setSignServiceHost
Content-Type: application/json
JSON Request Body 
{
  "host": "192.168.68.52"
}

9. Get Callback Host

Get this device's IP and port.

GET /getCallbackHost
Response 
{
  "host": "192.168.68.24",
  "port": 5000
}

Data Binding in SignStudio

Event to Label Binding

In SignStudio, configure a Label to display event data:

JSON Configuration 
{
  "$": {
    "player": "3241",
    "label": "Temperature Display"
  },
  "Data": [{
    "Label": [{
      "Text": ["Loading..."],
      "DataBinding": {
        "eventName": "myCustomEvent",
        "field": "name"
      }
    }]
  }]
}

When event myCustomEvent is received with {"name": "25.3"}, the label updates to show "25.3".

Event to Field Mapping

For complex data structures:

JSON Configuration 
{
  "DataBinding": {
    "eventName": "elevatorStatus",
    "field": "floor",
    "format": "Floor: {value}"
  }
}

Event data: {"floor": 5, "direction": "up"}
Display: "Floor: 5"

Event Commands (Outbound Events)

Configure SignPlayer to send events when user interacts:

Button Click Event

JSON Configuration 
{
  "$": {
    "player": "7000",
    "label": "Alarm Button"
  },
  "Data": [{
    "Button": [{
      "$": {
        "label": "Alarm ON",
        "fieldName": "alarmButton"
      }
    }],
    "EventCommands": [{
      "EventCommand": [{
        "$": {
          "from": "click",
          "command": "sendEvent"
        },
        "Params": {
          "eventName": "clickAlarm",
          "data": {
            "clickAlarm": "on"
          }
        }
      }]
    }]
  }]
}

Error Responses

Common Error Codes

Status Meaning
200 Success
400 Bad Request - Missing required parameters
404 Not Found - Invalid endpoint
500 Server Error - SignService internal error

Error Response Format

JSON 
{
  "success": false,
  "error": "Error description"
}

URL Encoding Reference

Characters that must be URL-encoded:

Character Encoded
: %3A
/ %2F
? %3F
& %26
= %3D
Space %20 or +

JavaScript Encoding

JavaScript 
const callbackUrl = `http://192.168.68.24:5001/callback`;
const encoded = encodeURIComponent(callbackUrl);
// Result: http%3A%2F%2F192.168.68.24%3A5001%2Fcallback

Rate Limiting and Timeouts

Rate Limits

Operation Recommendation
Send Events No hard limit, but avoid > 10 events/second
Register Events Re-registration recommended every 5-10 seconds
Callbacks SignService sends immediately, no batching

SignService Behavior

  • Callback timeout: 5 seconds per callback
  • Retry policy: 3 retries with exponential backoff
  • Failed callbacks: Logged but event continues to other callbacks

Node.js Re-registration Example

JavaScript 
// Re-register every N seconds to maintain connection
setInterval(async () => {
    try {
        await registerEventWithSignService(EVENT_NAME);
    } catch (e) {
        // Silently retry on next interval
    }
}, 5000);
Start | Login

live examples, see it in action

Checkout live examples of Digital Signage presentations. The SignPlayer can run everywhere, on Android, Windows, Mac, iPad and even inside your web browser

View More

product pricing

Find out why people call us “the world’s most popular digital signage platform”

View More

customers

Can it really be free?
What’s the catch?
Want to be amazed?
Read on...

View More