​

What are actions?

Actions let you trigger tasks on third-party APIs from your backend — like fetching recent Slack messages or creating a Salesforce contact. They’re flexible, composable units that can:

• Accept structured inputs
• Perform multiple API calls and transformations,
• Return a result (either synchronously or asynchronously).

For more details, see Action Overview.

​

Activate an action integration

To enable a pre-built action:

1. Go to the Integrations tab.
2. Select your integration.
3. Open the Endpoints tab.
4. Locate the desired action and enable it via the toggle.

​

Triggering actions

You can trigger actions from your backend using either:

• The Nango SDKs (reference)
• The HTTP API (reference)

​

Synchronous actions

Use synchronous actions when you want to receive a result immediately.

curl --request POST \
  --url https://api.nango.dev/action/trigger \
  --header 'Authorization: Bearer <ENV-SECRET-KEY>' \
  --header 'Connection-Id: <CONNECTION-ID>' \
  --header 'Provider-Config-Key: <INTEGRATION-ID>' \
  --data '{
    "action_name": "<ACTION-NAME>",
    "input": { ... }
  }'

curl --request POST \
  --url https://api.nango.dev/action/trigger \
  --header 'Authorization: Bearer <ENV-SECRET-KEY>' \
  --header 'Connection-Id: <CONNECTION-ID>' \
  --header 'Provider-Config-Key: <INTEGRATION-ID>' \
  --data '{
    "action_name": "<ACTION-NAME>",
    "input": { ... }
  }'

import { Nango }  from '@nangohq/node';

const nango = new Nango({ secretKey: '<ENV-SECRET-KEY>' });

const result = await nango.triggerAction({
  connectionId: '<CONNECTION-ID>',
  providerConfigKey: '<INTEGRATION-ID>',
  action: '<ATION-NAME>',
  input: { ... }
});

​

Asynchronous actions

Use asynchronous actions when:

• The task might take longer to complete
• You don’t need the action response immediately
• Actions should be retried for improved reliability
• You are sending many actions at once

To trigger asynchronously, add:

--header 'X-Async: true'

--header 'X-Async: true'

import { Nango }  from '@nangohq/node';

const nango = new Nango({ secretKey: '<ENV-SECRET-KEY>' });

// Trigger an asynchronous action
const { id, statusUrl } = await nango.triggerActionAsync('<INTEGRATION-ID>', '<CONNECTION-ID>', '<ACTION-NAME>', jsonInput);

// Later, retrieve the result
try {
  const result = await nango.getAsyncActionResult({ id });
  ...
} catch (error) {
  // handle error
}

You can also specify the maximum number of retries in case of failure using the X-Max-Retries header (the value must be between 0 and 5):

--header 'X-Max-Retries: 3'

​

Response format

When triggering an action asynchronously, the response will include a status URL and ID that you can use to poll to obtain the action result:

{
  "statusUrl": "/action/<ACTION-ID>",
  "id": "<ACTION-ID>"
}

​

Checking the action result

Poll the action result endpoint to check if the action has completed:

curl --request GET \
  --url https://api.nango.dev/action/<ACTION-ID> \
  --header 'Authorization: Bearer <PROJECT-SECRET-KEY>'

curl --request GET \
  --url https://api.nango.dev/action/<ACTION-ID> \
  --header 'Authorization: Bearer <PROJECT-SECRET-KEY>'

import { Nango }  from '@nangohq/node';

const nango = new Nango({ secretKey: '<PROJECT-SECRET-KEY>' });
const result = await nango.getAsyncActionResult({ id: '<ACTION-ID>' });
...

The behavior of the action result endpoint:

• Returns a 404 error if the action has not completed yet.
• Returns a 200 with the actual result data once the action completes successfully
• Returns a 500 with an error once the action completes with a failure.

​

Receiving webhook notifications

Instead of polling, configure webhooks to be notified when an async action completes.

1. Set up webhook endpoints in Environment Settings.
2. Enable webhooks for your environment.
3. When an action completes, Nango sends:

{
  "type": "async_action",
  "from": "nango",
  "connectionId": "<CONNECTION-ID>",
  "providerConfigKey": "<INTEGRATION-ID>",
  "payload": {
    "id": "<ACTION-ID>",
    "statusUrl": "/action/<ACTION-ID>"
  }
}

The webhook’s payload contains the same information as the initial response when triggering the action - an ID and status URL that you can use to retrieve the completed action result. After receiving this webhook, you can make a single API call to get the action result rather than repeatedly polling.

​

Troubleshoot errors & monitor

Navigate to the Logs tab to inspect potential errors & monitor action executions.