Notification Event

Info

Draft Documentation - This section is currently under review and may be subject to changes.

The notification event is sent via SSE when a new in-app notification is created for a player. This provides real-time delivery of important updates such as bonuses, promotions, account changes, and other player-relevant information.

Event Type

event_type: notification

Event Structure

{
  "brand_id": 1001,
  "player_id": 12345,
  "event_type": "notification",
  "event_data": {
    "message_id": "a7f8c934-1b2d-4e5f-9c8a-7d6e5f4a3b2c",
    "event": "bonus_granted",
    "event_details": {
      "bonus_amount": 100,
      "bonus_type": "welcome",
      "currency": "USD"
    },
    "is_read": false,
    "time": "2025-10-22 14:30:45"
  }
}

Fields

Base Event Fields

Field Type Description
brand_id int The casino brand identifier.
player_id int The player identifier.
event_type string Always “notification” for this event type.
event_data object Notification-specific data (see below).

Event Data Fields

Field Type Description
message_id string Unique notification identifier (UUID).
event string Notification event type (e.g., “bonus_granted”, “promotion_available”).
event_details object Event-specific details (flexible JSON structure).
is_read boolean Whether the notification has been read (always false for new notifications).
time string Notification creation timestamp in format “YYYY-MM-DD HH:MM:SS”.

Event Examples

Example 1: Bonus Granted Notification

This notification is sent when a player receives a bonus.

{
  "brand_id": 1001,
  "player_id": 12345,
  "event_type": "notification",
  "event_data": {
    "message_id": "a7f8c934-1b2d-4e5f-9c8a-7d6e5f4a3b2c",
    "event": "bonus_granted",
    "event_details": {
      "bonus_amount": 100,
      "bonus_type": "welcome",
      "currency": "USD",
      "bonus_id": 789
    },
    "is_read": false,
    "time": "2025-10-22 14:30:45"
  }
}

Example 2: Promotion Available Notification

This notification is sent when a new promotion becomes available for a player.

{
  "brand_id": 1001,
  "player_id": 12345,
  "event_type": "notification",
  "event_data": {
    "message_id": "b8e9d045-2c3e-5f6g-0d9b-8e7f6g5b4c3d",
    "event": "promotion_available",
    "event_details": {
      "promo_id": "PROMO123",
      "promo_name": "Weekend Reload Bonus",
      "expires_at": "2025-11-15",
      "conditions": {
        "min_bet": 100,
        "multiplier": 3,
        "max_bonus": 500
      }
    },
    "is_read": false,
    "time": "2025-10-22 15:00:00"
  }
}

Example 3: Deposit Success Notification

This notification is sent after a successful deposit.

{
  "brand_id": 1001,
  "player_id": 12345,
  "event_type": "notification",
  "event_data": {
    "message_id": "c9f0e156-3d4f-6g7h-1e0c-9f8g7h6c5d4e",
    "event": "deposit_success",
    "event_details": {
      "amount": 250.00,
      "currency": "USD",
      "payment_method": "credit_card",
      "transaction_id": "TXN987654"
    },
    "is_read": false,
    "time": "2025-10-22 16:15:30"
  }
}

Example 4: KYC Approved Notification

This notification is sent when KYC verification is approved.

{
  "brand_id": 1001,
  "player_id": 12345,
  "event_type": "notification",
  "event_data": {
    "message_id": "d0g1f267-4e5g-7h8i-2f1d-0g9h8i7d6e5f",
    "event": "kyc_approved",
    "event_details": {
      "verification_level": "basic",
      "approved_at": "2025-10-22 17:00:00",
      "limits_updated": true
    },
    "is_read": false,
    "time": "2025-10-22 17:00:05"
  }
}

Example 5: Account Update Notification

This notification is sent for important account changes.

{
  "brand_id": 1001,
  "player_id": 12345,
  "event_type": "notification",
  "event_data": {
    "message_id": "e1h2g378-5f6h-8i9j-3g2e-1h0i9j8e7f6g",
    "event": "account_update",
    "event_details": {
      "update_type": "email_changed",
      "new_email": "new****@example.com",
      "requires_verification": true
    },
    "is_read": false,
    "time": "2025-10-22 18:00:00"
  }
}

Example 6: Tournament Win Notification

This notification is sent when a player wins a tournament.

{
  "brand_id": 1001,
  "player_id": 12345,
  "event_type": "notification",
  "event_data": {
    "message_id": "f2i3h489-6g7i-9j0k-4h3f-2i1j0k9f8g7h",
    "event": "tournament_win",
    "event_details": {
      "tournament_id": "123456-13456-123456-123456",
      "transaction_id": "123123",
      "tournament_name": "Tournament Name",
      "tournament_points": 1500,
      "tournament_start_date": "2025-08-20 00:00:00",
      "tournament_end_date": "2025-08-27 00:00:00",
      "tournament_position": 1,
      "template_id": "1",
      "prize_type": 1,
      "player_id": 12345,
      "casino_id": 1001,
      "prize_value": "100",
      "prize_name": "test",
      "total_rounds": 10,
      "total_bets": "450",
      "total_wins": "1425",
      "timestamp": "2025-08-27 00:00:00"
    },
    "is_read": false,
    "time": "2025-08-27 00:00:05"
  }
}

Common Event Types

The notification system supports various event types. Here are the most common:

Event Type Description
bonus_granted Player received a bonus
promotion_available New promotion available for player
deposit_success Successful deposit transaction
withdrawal_approved Withdrawal request approved
kyc_approved KYC verification approved
kyc_rejected KYC verification rejected
account_update Important account changes
tournament_update Tournament status or position change
tournament_win Player won a tournament
limit_reminder Responsible gaming limit reminder
document_required Additional documents needed

Event Details Structure

The event_details field is a flexible JSON object that can contain any event-specific data. The structure varies based on the event type. Common patterns include:

  • Amount-based events: Include amount, currency fields
  • Time-based events: Include expires_at, valid_until fields
  • Status updates: Include status, previous_status fields
  • Reference data: Include transaction_id, bonus_id, promo_id fields

Client Implementation

JavaScript Example

const eventSource = new EventSource('/gateway/sse/1001/stream', {
  headers: {
    'x-auth-token': playerToken
  }
});

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  // Filter for notification events
  if (data.event_type === 'notification') {
    const notification = data.event_data;

    // Handle based on event type
    switch (notification.event) {
      case 'bonus_granted':
        showBonusNotification(notification);
        break;
      case 'promotion_available':
        showPromotionNotification(notification);
        break;
      case 'deposit_success':
        showDepositConfirmation(notification);
        break;
      default:
        showGenericNotification(notification);
    }

    // Update notification center
    addToNotificationCenter(notification);
  }
};

function showBonusNotification(notification) {
  const { bonus_amount, currency, bonus_type } = notification.event_details;
  showToast(`You received a ${bonus_type} bonus of ${bonus_amount} ${currency}!`);
  playNotificationSound();
  incrementNotificationBadge();
}

Publishing Notification Events

Notification events are automatically published by the go_marketing service when a new notification is created:

// From go_marketing/services/notifications_service.go
func (service *NotificationsService) InsertNewNotifications(
  ctx context.Context,
  notifications []domain.Notification
) error {
  // Insert into database
  err := service.notificationsDao.InsertNotification(ctx, notifications)
  if err != nil {
    return err
  }

  // Publish SSE event for each notification
  for _, notification := range notifications {
    eventData := map[string]interface{}{
      "message_id":    notification.MessageID,
      "event":         notification.Event,
      "event_details": notification.EventDetails,
      "is_read":       notification.IsRead,
      "time":          notification.Time.Format("2006-01-02 15:04:05"),
    }

    service.sseService.Publish(
      ctx,
      notification.BrandId,
      notification.PlayerId,
      sse.SSENotificationEvent,
      eventData,
    )
  }

  return nil
}

Integration with Notification Center

When a notification event is received via SSE:

  1. Display a real-time toast/popup notification to the player
  2. Add the notification to the notification center UI
  3. Increment the unread notification badge count
  4. Optionally play a sound or show a browser notification

To retrieve the full list of notifications (including older ones), use the Get Notifications endpoint.

To mark notifications as read, use the Mark Notifications as Read endpoint.

Performance Considerations

  • Delivery Latency: Typical delivery time is < 100ms from publication to client
  • Buffer Size: The SSE system can buffer up to 50 events per connection
  • No Persistence: SSE events are not persisted; disconnected clients miss events
  • Database Backup: All notifications are also stored in the database for 90 days

Best Practices

  1. Deduplication: Check message_id to avoid processing duplicate notifications
  2. Graceful Degradation: If SSE is unavailable, poll the GET notifications endpoint
  3. User Control: Allow users to control notification preferences and types
  4. Visual Feedback: Provide clear visual indication of new vs. read notifications
  5. Persistence: Store notifications locally for offline access
  6. Throttling: Avoid overwhelming users with too many simultaneous notifications

See Also