Event Types

All SSE event types with full payload schemas.

The Event Hook API emits 4 tip event types plus a connected system event. All events are delivered as SSE data: lines containing a JSON object with a type field.

Envelope Format

Every SSE message is a single data: line followed by two newlines:

data: {"type":"tip:received","tipId":"abc123",...}

Each message is terminated by two newline characters (\n\n) per the SSE specification.

Parse events by reading the type field from the JSON payload:

source.onmessage = (event) => {
  const payload = JSON.parse(event.data);
  switch (payload.type) {
    case "tip:received":
      // handle tip
      break;
    case "tip:goal-completed":
      // handle goal completion
      break;
  }
};

System Events

`connected`

Sent immediately after the SSE connection is established. Confirms authentication succeeded and the upstream WebSocket is open.

json

{ "type": "connected" }

No additional fields. Use this event to confirm your client is receiving data.

Tip Events

tip:received

Fired when a tip is processed for your campaign. This is the most common event.

Field	Type	Description
type	'tip:received'	Event type identifier
tipId	string	Unique tip identifier
amount	number	Tip amount in cents (e.g., 500 = $5.00)
displayName	string	Tipper's display name
message	string \| null	Optional message from tipper
isAnonymous	boolean	Whether the tip was sent anonymously
goalId	string \| null	Goal this tip was applied to, if any
goalProgress	number \| null	Current goal progress in cents after this tip
goalTarget	number \| null	Goal target amount in cents
timestamp	string	ISO 8601 timestamp of when the tip was processed

Example payload:

json

{
  "type": "tip:received",
  "tipId": "clx1abc2def34",
  "amount": 500,
  "displayName": "Jamie",
  "message": "Keep it up!",
  "isAnonymous": false,
  "goalId": "clx9goal1234",
  "goalProgress": 1500,
  "goalTarget": 5000,
  "timestamp": "2026-04-07T18:30:00.000Z"
}

Info

amount, goalProgress, and goalTarget are in cents. Divide by 100 for display (e.g., 500 = $5.00).

When the tip is anonymous, isAnonymous is true and displayName reflects the anonymous label (not the real user).

When no goal is active, goalId, goalProgress, and goalTarget are null.

tip:goal-completed

Fired when a tip causes a goal to reach its target amount. If a single tip completes multiple goals via overflow, you receive one event per goal.

Field	Type	Description
type	'tip:goal-completed'	Event type identifier
goalId	string	ID of the completed goal
goalName	string	Display name of the completed goal
goalTarget	number	Goal target amount in cents
overflowAmount	number	Amount in cents that exceeded the goal target
nextGoal	object \| null	Next goal in the queue (id, description, amount, progress), or null if none
chainIndex	number	Position of this goal in the overflow chain (0-based)
chainTotal	number	Total goals completed in this overflow chain

Example payload:

json

{
  "type": "tip:goal-completed",
  "goalId": "clx9goal1234",
  "goalName": "New Webcam Fund",
  "goalTarget": 5000,
  "overflowAmount": 200,
  "nextGoal": {
    "id": "clx9goal5678",
    "description": "Lighting Upgrade",
    "amount": 10000,
    "progress": 200
  },
  "chainIndex": 0,
  "chainTotal": 1
}

nextGoal is null if no more goals are queued. overflowAmount is the cents that spilled into the next goal.

When a tip completes multiple goals, chainIndex (0-based) and chainTotal indicate position in the chain. A single-goal completion has chainIndex: 0, chainTotal: 1.

tip:overflow-chain

A summary event fired once after a single tip completes two or more goals in sequence. Not fired for single-goal completions.

Field	Type	Description
type	'tip:overflow-chain'	Event type identifier
tipId	string	ID of the tip that triggered the chain
totalAmount	number	Total tip amount in cents
goalsCompleted	number	Number of goals completed by this single tip
goalIds	string[]	IDs of all goals completed in order

Example payload:

json

{
  "type": "tip:overflow-chain",
  "tipId": "clx1abc2def34",
  "totalAmount": 15000,
  "goalsCompleted": 3,
  "goalIds": ["clx9goal1234", "clx9goal5678", "clx9goal9012"]
}

tip:queue-updated

Fired when the goal queue changes — a goal is completed, added, removed, or reordered. Use this to keep a dashboard or overlay in sync.

Field	Type	Description
type	'tip:queue-updated'	Event type identifier
activeGoal	object \| null	Currently active goal (id, description, amount, progress), or null
goalCount	number	Total number of goals in the queue
completedGoalCount	number	Number of goals completed so far

Example payload:

json

{
  "type": "tip:queue-updated",
  "activeGoal": {
    "id": "clx9goal5678",
    "description": "Lighting Upgrade",
    "amount": 10000,
    "progress": 200
  },
  "goalCount": 4,
  "completedGoalCount": 2
}

activeGoal is null when all goals are completed or none are set.