​
Widget Events API

Push custom events to all widgets in an overlay via HTTP POST.

​
Endpoint

POST /v1/features/sbcanvas/events/{channel_id}

​
Request

curl -X POST https://api.streambot.co/v1/features/sbcanvas/events/ch_abc123 \
  -H "Authorization: Bearer sb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"event": "custom:confetti", "data": {"count": 200}}'

​
Request Body

{
  "event": "custom:confetti",
  "data": {
    "count": 200,
    "color": "#ff00ff",
    "duration": 3000
  }
}
FieldTypeRequiredDescription
eventstringYesEvent name (must start with custom:)
dataobjectNoArbitrary JSON payload

​
Event Name Rules

  • Must start with custom: prefix
  • Max length: 64 characters
  • Allowed characters: a-z, 0-9, :, _, -
  • Examples: custom:confetti, custom:score_update, custom:poll:start

​
Response

{
  "success": true,
  "delivered_to": 1
}
delivered_to — number of overlay instances that received the event. Returns 0 if the overlay is offline.

​
Delivery Behavior

  • Events are delivered in real-time via WebSocket
  • If the overlay is disconnected, events are dropped (not queued)
  • Delivery is best-effort — no retry mechanism

​
Receiving in Widgets

// REST sends: { "event": "custom:confetti", "data": {"count": 200} }
// Widget receives on:
SBCanvas.on('widget:event:custom:confetti', (data) => {
  // data = { count: 200 }
  SBCanvas.confetti({ count: data.count });
});

​
Use Cases

IntegrationEvent Example
Stream deck buttoncustom:confetti
Chatbot commandcustom:poll:start
Scoreboard appcustom:score_update
Webhook relaycustom:donation:goal

​
Error Codes

StatusCodeDescription
401unauthorizedInvalid or missing Bearer token
404not_foundChannel ID doesn’t exist
422validation_errorMissing event field or invalid format
429rate_limit_exceededMore than 60 requests per minute