​
Widget Events

External systems (stream decks, chatbots, dashboards, webhooks) can push custom events to your overlay widgets via the REST API. Your widget listens for these events through the standard event bus.

​
Listening for Widget Events

SBCanvas.on('widget:event:custom:confetti', (data) => {
  SBCanvas.confetti({ count: data.count || 100 });
});

SBCanvas.on('widget:event:custom:score_update', (data) => {
  SBCanvas.vars.set('score', data.score);
});

SBCanvas.on('widget:event:custom:alert', (data) => {
  showCustomAlert(data.message, data.duration);
});

​
Event Naming

Events sent via the REST API arrive prefixed with widget:event::
REST API event fieldWidget hears
custom:confettiwidget:event:custom:confetti
custom:score_updatewidget:event:custom:score_update
custom:poll:startwidget:event:custom:poll:start

​
Local Widget Events (via emit)

Events emitted locally with SBCanvas.emit() are prefixed with widget: (no event: segment): 
// Emitting
SBCanvas.emit('combo-hit', { count: 10 });

// Listening (in same or other widgets)
SBCanvas.on('widget:combo-hit', (data) => {
  console.log(`Combo: ${data.count}`);
});

​
Comparison

Sourceemit formatlisten format
REST APIcustom:confettiwidget:event:custom:confetti
Local SBCanvas.emit()'combo-hit'widget:combo-hit

​
Example: Stream Deck Integration

A stream deck button sends a REST event to trigger confetti: 
SBCanvas.on('widget:event:custom:confetti', (data) => {
  SBCanvas.confetti({
    count: data.count || 200,
    spread: data.spread || 70,
    duration: data.duration || 3000
  });
  if (data.sound) {
    SBCanvas.sound('/sounds/celebrate.mp3', 0.8);
  }
});

​
Example: Chatbot Commands

A chatbot sends events when viewers use commands: 
SBCanvas.on('widget:event:custom:poll:start', (data) => {
  startPoll(data.question, data.options, data.duration);
});

SBCanvas.on('widget:event:custom:poll:vote', (data) => {
  addVote(data.option, data.username);
});

SBCanvas.on('widget:event:custom:poll:end', () => {
  endPoll();
});