App set-up events

App set up can detail key lifecycle and custom system events through event handlers. These are defined inside your app’s index.js file under the eventHandlers object.

These handlers allow you to run code automatically when your app is installed, uninstalled, or triggered via a custom event.

eventHandlers: {
  onAppInstall: {
    run: async (r, args) => { 
      // logic on installation
    }
  },
  onAppUninstall: {
    run: (r, args) => {
      // logic on uninstallation
    }
  },
  onCustomEvent: {
    run: async (r, args) => {
      // logic for a custom trigger
    }
  }
}

Parameters

Each handler receives two parameters:

r: Rocketlane runtime context — includes helper utilities like logging, storage access, HTTP clients, etc.

args: An object with event-specific data such as installationId, user context, config values, and more.

@chai/Nisha to add a sample args object

Supported Set-up Events

1. onAppInstall

Runs automatically when your app is installed.

Use cases:

• Initialize app configurations
• Register webhooks
• Create system resources
• Log the installation event

2. onAppUninstall

Runs automatically when a user removes your app.

Use cases:

• Clean up storage or credentials
• Deregister any connected services
• Cancel background jobs
• Log uninstall activity

3. onCustomEvent

Runs when you manually invoke a custom event from Rocketlane or an external system (e.g. webhook trigger, scheduled task).

Use cases:

• Handle custom workflows
• Sync data from external tools
• Trigger event-based actions

Example: Basic Install Handler

eventHandlers: {
  onAppInstall: {
    run: async (r, args) => {
      const { installationId, config, context } = args;
      r.log.info(`Installed app with ID: ${installationId}`);
      
      // You could register a webhook here
      // or store config values in Rocketlane's storage
    }
  }
}