Pre-requisite: configure Nango.

​
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).
The output of an action cannot exceed 10MB.
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.
If the action you need isn’t available, create a custom action integration.

​
Triggering actions

You can trigger actions from your backend using either:
Actions can be executed synchronously (returning the result immediately) or asynchronously (returning a status URL you can poll or listen via webhook).

​
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": { ... }
  }'
You can also use the generated endpoint specific to your integration, shown in the Endpoints tab. It provides tailored input/output docs for each action.

​
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'
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'
When using retries with asynchronous actions, make sure your action logic is idempotent. This means that running the action multiple times with the same input should produce the same result without unwanted side effects.

​
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>'
Execution timing for asynchronous actions is not guaranteed. Actions are currently processed sequentially per environment, so execution time depends on how many actions are triggered and how long each one runs. Design your implementation to handle potential delays.
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.
Questions, problems, feedback? Please reach out in the Slack community.