​
Widget Events REST API

Send custom events to any connected overlay using a simple HTTP POST.

​
Endpoint

POST https://api.streambot.co/v1/features/sbcanvas/events/{channel_id}

​
Authentication

Authorization: Bearer sb_live_xxxxxxxxxxxx
Generate API keys in the StreamBot dashboard under Settings > API Keys.

​
Request Body

{
  "event": "custom:confetti",
  "data": { "count": 200, "color": "#8B5CF6" }
}
FieldTypeRequiredDescription
eventstringYesEvent name (must start with custom:)
dataobjectNoArbitrary payload delivered to widgets

​
Response

{
  "success": true,
  "delivered_to": 1
}
delivered_to indicates how many overlay instances received the event. If the overlay is offline, events are dropped (not queued).

​
Rate Limits

LimitValue
Requests per minute60
Exceeding the limit returns 429 Too Many Requests.

​
Error Codes

StatusMeaning
401Invalid or missing token
404Channel not found
422Invalid request body (missing event field, bad format)
429Rate limited

​
cURL Examples

# Trigger confetti
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}}'

# Update scoreboard
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:score", "data": {"team": "blue", "score": 7}}'

# Show custom alert
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:alert", "data": {"message": "Hello from the API!"}}'

​
Python Example

import requests

headers = {
    "Authorization": "Bearer sb_live_xxxx",
    "Content-Type": "application/json"
}

requests.post(
    "https://api.streambot.co/v1/features/sbcanvas/events/ch_abc123",
    headers=headers,
    json={"event": "custom:confetti", "data": {"count": 200}}
)

​
Node.js Example

const res = await fetch(
  'https://api.streambot.co/v1/features/sbcanvas/events/ch_abc123',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sb_live_xxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ event: 'custom:confetti', data: { count: 200 } })
  }
);

​
Receiving in Widgets

Events arrive through the standard event bus prefixed with widget:event:: 
// REST sends: { "event": "custom:confetti", ... }
// Widget receives:
SBCanvas.on('widget:event:custom:confetti', (data) => {
  SBCanvas.confetti({ count: data.count });
});