​
Synchronous or asynchronous execution

Both execution models have different trade-offs.
Execution modeProsConsBest fit for
Synchronous
  • Immediate result
  • Simple error handling
  • Easier to debug
  • You need to handle rate limits
  • You need to handle concurrency
  • Real-time user interactions
  • Freshness of data is important (e.g., current settings)
Asynchronous
  • Handles rate limits and retries automatically
  • Scales to large/batch workloads
  • ”Fire and forget” execution
  • Result is not immediate
  • Requires polling or webhook handling
  • More complex error handling
  • Bulk or bursty workloads
  • Endpoints with very low rate limits
  • Batch writes

​
Executing action asynchronously

To trigger an action asynchronously, add the X-Async header or use the triggerActionAsync SDK method. 
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>' \
  --header 'X-Async: true'
  --data '{
    "action_name": "<ACTION-NAME>",
    "input": { ... }
  }'
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 webhooks from Nango to your app
  2. Enable the Async action completed webhook 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 and monitor action executions.
Questions, problems, feedback? Please reach out in the Slack community.