Skip to main content

Documentation Index

Fetch the complete documentation index at: https://nango.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Event functions run automatically when Nango reaches a connection lifecycle event. They are defined with createOnEvent(). Use them to validate credentials, register provider webhooks, seed connection-specific metadata, or clean up external resources before a connection is deleted.

​
Choose the lifecycle event

Supported events:
EventWhen it runsCommon use
validate-connectionDuring connection creationReject invalid credentials or missing provider permissions
post-connection-creationImmediately after a connection is createdRegister provider webhooks, seed metadata, run setup checks
pre-connection-deletionBefore a connection is deletedDelete provider webhook subscriptions or external resources
Before generating an event function, identify the lifecycle event, provider endpoint, required metadata, and desired failure behavior.For validate-connection, throwing rejects and deletes the connection. For cleanup functions, make the provider call idempotent because the external resource may already be gone.

​
Create a setup function

Add a file under the integration’s on-events/ folder:
salesforce/on-events/register-webhook.ts
import { createOnEvent } from 'nango';

export default createOnEvent({
    description: 'Register a Salesforce webhook after a connection is created',
    event: 'post-connection-creation',
    exec: async (nango) => {
        const response = await nango.post({
            endpoint: '/webhooks',
            data: {
                url: 'https://api.myapp.com/webhooks/salesforce',
                events: ['contact.updated']
            }
        });

        await nango.setMetadata({
            webhookId: response.data.id
        });
    }
});
Import it from index.ts:
index.ts
import './salesforce/on-events/register-webhook';

​
Create a cleanup function

If the provider webhook is registered per connection, clean it up before the Nango connection is deleted:
salesforce/on-events/delete-webhook.ts
import { createOnEvent } from 'nango';
import * as z from 'zod';

const Metadata = z.object({
    webhookId: z.string().optional()
});

export default createOnEvent({
    description: 'Delete the Salesforce webhook before connection deletion',
    event: 'pre-connection-deletion',
    metadata: Metadata,
    exec: async (nango) => {
        const metadata = await nango.getMetadata();
        if (!metadata?.webhookId) {
            return;
        }

        await nango.delete({
            endpoint: `/webhooks/${metadata.webhookId}`
        });
    }
});
Import it from index.ts:
index.ts
import './salesforce/on-events/delete-webhook';

​
Test and deploy

Dry run an event function against an existing connection: 
nango dryrun register-webhook '<CONNECTION-ID>' -e dev
Deploy your functions: 
nango deploy
Event functions run automatically when their configured event occurs. Your app does not trigger them directly.