Skip to main content

​
What are lifecycle events?

Lifecycle events let you customize Nango’s behavior at different points in a Connection’s lifecycle. When certain things happen for a Connection, Nango triggers an event. You can register an event handler Function for a specific event and integration. Example: You register a post-connection-creation event handler on your Salesforce integration. Nango will call this function once for each Salesforce connection, immediately after it has been created. All lifecycle event executions are logged in Nango’s logs.

​
Supported lifecycle events

EventDescription
validate-connectionOccurs when a connection is being created. Allows custom validation of credentials. Rejects and deletes the connection if validation fails.
post-connection-creationOccurs immediately after a connection has been created.
pre-connection-deletionOccurs before a connection is deleted.
See the lifecycle events reference for details.

​
Common use cases

  • Credential validation: Integration-specific validation logic for API keys (e.g., check permissions to access a specific endpoint)
  • Webhook registration: Register webhook subscriptions after a connection has been created
  • Account configuration: Fetch account configuration information from the external API
  • Cleanup on deletion: Deregister webhook subscriptions or revoke access tokens when a connection is deleted

​
How to implement an event handler

​
Step 1 - Initial Functions setup

If you don’t have a nango-integrations folder yet, follow the initial Functions setup guide first.

​
Step 2 - Create your event function file

Create a new file in your integration’s on-events folder: 
nango-integrations/
├── .nango
├── .env
├── index.ts
├── package.json
└── salesforce/
    └── on-events/
        └── setup.ts
The integration folder name (e.g., salesforce) must match an integration ID in your Nango dashboard.
Paste the following scaffold into the file:
setup.ts
import { createOnEvent } from 'nango';

export default createOnEvent({
    description: "<description of your event handler>",
    event: 'post-connection-creation', // or 'pre-connection-deletion' or 'validate-connection'
    exec: async (nango) => {
        // Your integration code goes here.
    }
});
Import your new event file in your index.ts file:
index.ts
import './salesforce/on-events/setup';

​
Step 3 - Implement the event function

Implement your handler logic in the exec function. The function kicks off when the associated event occurs. Helpful resources:

​
Step 4 - Deploy your integrations

Deploy your event function to an environment in your Nango account: 
nango deploy dev
Questions, problems, feedback? Please reach out in the Slack community.