Dev Updates - Nango Docs

January 6, 2025

Sync cache: new data retention policies

✨ What’s changing

Nango introduces automatic data retention policies for records stored in the Nango sync cache. These policies apply to synced records produced by syncs (our replication-oriented functions) and ensure that record payloads are not retained indefinitely.

Retention lifecycle

1. Automated payload pruningIf a record has not been updated for 30 days, Nango will automatically prune its payload. The record still exists and its metadata remains intact, including record ID, sync state and payload hash (used for change detection). After pruning, the record’s data fields are no longer retrievable from the Nango cache, but Nango can still track the record and detect future changes. This pruning does not impact sync execution or delta-detection.2. Automated hard deletionIf a sync has not executed for 60 days, records belonging to that sync will be permanently deleted (payload + metadata).

🗓️ Timeline

The new data retention policies will start on January 8, 2026. Record payload pruning will start 30 days later. Record hard deletion for inactive syncs will start 60 days later.

🧐 Am I impacted?

Most customers (including most sync users) are not impacted, in particular if you use syncs for replication, receiving updates via Nango webhooks, and replicating records into your own system shortly after they arrive in the Nango cache.You are impacted if you use Nango sync’s cache as a long-term persistent data store, reading/editing record payloads from the Nango cache long after they were updated.

💡 What should I do?

If you fetch record payloads from Nango long after they were updated (30+ days), reach out. We will make sure you do not experience breaking changes.

Why are we making this change?

These retention policies are part of our broader commitment to helping customers meet modern data compliance and security expectations. They ensure that sensitive user data is not stored indefinitely in the Nango sync cache when it is no longer needed for syncing.

December 5, 2025

New HMAC-based webhook signature header

Nango webhooks now include a new X-Nango-Hmac-Sha256 header that uses HMAC-SHA256 for improved security. The legacy X-Nango-Signature header (which uses plain SHA-256 with key concatenation) is still sent for backwards compatibility but should no longer be used.

🗓️ Timeline

Now available: The X-Nango-Hmac-Sha256 header is already included in all webhook requests.
The X-Nango-Signature header will continue to be sent for backwards compatibility, with no current deprecation timeline.

🧐 Am I impacted?

If you’re currently verifying webhooks using the X-Nango-Signature header
If you’re implementing webhook verification for the first time

💡 What should I do?

For new integrations:

Use the X-Nango-Hmac-Sha256 header to verify webhook signatures
See the updated webhook documentation for code examples

For existing integrations:

Migrate to using X-Nango-Hmac-Sha256 when convenient
The old X-Nango-Signature header will continue to work, but we recommend migrating for better security

Why are we making this change?

HMAC-SHA256 is cryptographically more secure than plain SHA-256 with concatenation. HMAC provides better protection against length extension attacks and is the industry standard for webhook signature verification.

November 27, 2025

Behavior change of webhooks from Nango to your app

New behavior:

Timeout: 20s (instead of 60s)
Retries: 2 (instead of 7)

🗓️ Timeline

New behavior will go live on December 3, 2025.

🧐 Am I impacted?

Most likely. In particular, if you consume webhooks for auth, syncs, async actions, webhook forwards.

💡 What should I do?

No action to take.

Why are we making this change?

The long timeout and many retries created incidents when webhook endpoints were unavailable. The new behavior is in line with other popular APIs (e.g. Stripe, Hubspot).

October 29, 2025

Function custom logs won’t be ingested by default for remote environments

Function custom logs are calls to nango.log(...) in your functions (actions, syncs, webhooks, and on-event handlers).Starting in November, only warn and error level logs will be ingested by default for remote environments. Debug and info level logs will no longer be ingested automatically. This means that when you call nango.log(...) without an explicit level (which defaults to info), these logs will not appear in the Nango UI logs tab for remote environments.All function custom logs, regardless of log level, will continue to surface in your local console when using the nango dryrun CLI command.

🗓️ Timeline

November 1, 2025: Only warn and error level logs will be ingested for remote environments by default.

🧐 Am I impacted?

If you use custom logs in your syncs and actions with nango.log(...)
If you rely on viewing debug and info level logs in the Nango UI logs tab for remote environments

💡 What should I do?

If you want to continue viewing custom logs in the Nango UI logs tab, you have three options:Option 1: Increase the log level of individual log calls

nango.log('Important information', { level: 'warn' });
nango.log('Critical error occurred', { level: 'error' });

Option 2: Modify the minimum log level for the entire function run

nango.logger({
  level: 'info' // info-level logs and above (warn & error) will be indexed
});

// Now all your regular nango.log() calls will be ingested
nango.log('This will now appear in the UI');

Option 3: Set environment variable to revert to original behaviorWhile this is the simplest way to restore the previous behavior, we recommend using Options 1 or 2 instead for better cost control.In your environment settings in the Nango UI, create an environment variable with key NANGO_LOGGER_LEVEL and value 'info' (or 'debug', 'warn', 'error').⚠️ Warning: This will ingest all function logs across all your syncs and actions. Carefully monitor your log volume starting in November to avoid unexpectedly high bills.Important notes:

Options 1 and 2 require changes in your functions’ code and must be deployed using the Nango CLI
Option 3 can be configured directly in the Nango UI without code changes
Local development is unaffected - all logs continue to appear when using nango dryrun
This change helps ensure you’re only billed for logs you actively use in production

Why are we making this change?

Many customers generate a large number of custom logs for local development purposes without using them in their remote environments. With the new pricing model starting in November (which includes generous included usage for function custom logs), this change ensures that customers don’t get billed for logs they’re not actively using.

September 1, 2025

End-user info is no longer shared between connections

Currently, if multiple connections share the same end_user_id, they also share the same end-user object in Nango. After the change, each connection will always get its own independent copy of the end-user object, even if they use the same end_user_id. We are changing the old behavior because it was confusing for some developers, and it was impossible to declare multiple organizations for a given user.

🗓️ Timeline

September 8, 2025: End user updates will stop being replicated across connections.

🧐 Am I impacted?

If your users can be tied to multiple organizations
If you were relying on the end user auto-replication to maintain data freshness

💡 What should I do?

End user fields are mostly for display and tagging purposes:

If you are not using them, you can safely ignore this update.
If you are using them, and wish to keep them in sync (e.g: display name, across connections) you will need to patch each connection when your end user is updated on your side

await nango.patchConnection({
  connectionId,
  provider_config_key
} , {
  end_user: {
    id: '123',
    email: 'new-email@nango.dev'
  }
});

NB: if you don’t keep them in sync, the only side effect is that data will be stale in the Nango platform.There is no batch endpoint for this operation. If you need one, please reach out on Slack.

August 22, 2025

Action payload output limit

Nango actions currently have a documented output limit of 10MB. We are further restricting that limit to 2MB. Instead of using an action for large payloads like this, we encourage usage of the Nango proxy.Additionally, we will also soon restrict action inputs so please take note of your inputs.

🗓️ Timeline

October 1, 2025: We will throw an error when an action output exceeds the stated limitation of 2MB.

🧐 Am I impacted?

If you use actions and have a heavy output from the action. Typically the actions that have a large output are fetch-attachment, fetch-call-transcripts and in general any fetching any object from an external system. We have added dedicated proxy code for such operations to help with the migration: fetch-document, fetch-spreadsheet, fetch-file, fetch-database
If you’re using a now deprecated prebuilt template that fetches objects from an external system

💡 What should I do?

Check your action logs for a warning that you’ve exceeded the action output limitation.
Verify the actions you’re using and log the output size of the action
Migrate the action to use the proxy instead

If your action logs exceed the 2MB limitation you’ll now see a warning like this

Please reach out with any questions or concerns in our Slack community.

August 20, 2025

Deprecation of `/connection` endpoints

In this release, we’ve made some changes to the API that are breaking for some users.

All endpoints under /connection are now deprecated. Use the new /connections endpoint instead. They all, except one, take and return the same data. Only the base path has changed.
The endpoint POST /connections (previously POST /connection) now takes a different body, but returns the same data as previously. This new body is more flexible and ensure stricter typings on your side and validation on our side.
The endpoint POST /connection/:connectionId/metadata and PATCH /connection/:connectionId/metadata who have been deprecated for a while will not be migrated to /connections and will be removed at the end of the grace period.

🗓️ Timeline

January 20, 2026: All /connection endpoints will be removed.

🧐 Am I impacted?

If you manually use any endpoint under /connection
If you use the CLI
If you use the official Nango SDKs

💡 What should I do?

If you use the CLI, you should upgrade to >=0.67.0
If you use the official Nango SDKs, you should upgrade to >=0.67.0
If you manually use any endpoint under /connection, you should migrate to /connections
If you use the POST /connection/:connectionId/metadata or PATCH /connection/:connectionId/metadata endpoints, you should migrate to /connections/metadata
If you specifically use the POST /connection endpoint to import connections, check the migration section below.

Migrating to `POST /connections`

Only this endpoint requires a manual migration. Previously, the credentials were all at the root of the body.

curl -X POST https://api.nango.dev/v1/connection \
-H "Authorization: Bearer <your-secret-key>" \
-H "Content-Type: application/json" \
-d '{
  "provider_config_key": "slack",
  "access_token": "some-access-token",
  [...]
}'

Now they are nested under the credentials key:

curl -X POST https://api.nango.dev/v1/connections \
-H "Authorization: Bearer <your-secret-key>" \
-H "Content-Type: application/json" \
-d '{
  "provider_config_key": "slack",
  "credentials": {
    "type": "OAUTH2",
    "access_token": "some-access-token",
    [...]
  }
}'

Please report any inconsistencies or issues with the new endpoints in our slack community.

July 21, 2025

Deprecation of `nango.yaml` configuration file

The new script format is now officially released under >=0.64.0. If you are already using it or have tried before, the only big change between beta and now is that we now use zod v4. By upgrading to >=0.64.0 and running nango compile, the CLI will update the dependency automatically; otherwise, you need to install zod: 4.0.5

🗓️ Timeline

December 1st, 2025: nango.yaml support will be removed.

🧐 Am I impacted?

If you use custom scripts

💡 What should I do?

Follow migration guide -> https://nango.dev/docs/guides/custom-integrations/migrate-to-zero-yaml

Changelog

​Sync cache: new data retention policies

​✨ What’s changing

​Retention lifecycle

​🗓️ Timeline

​🧐 Am I impacted?

​💡 What should I do?

​Why are we making this change?

​New HMAC-based webhook signature header

​🗓️ Timeline

​🧐 Am I impacted?

​💡 What should I do?

​Why are we making this change?

​Behavior change of webhooks from Nango to your app

​🗓️ Timeline

​🧐 Am I impacted?

​💡 What should I do?

​Why are we making this change?

​Function custom logs won’t be ingested by default for remote environments

​🗓️ Timeline

​🧐 Am I impacted?

​💡 What should I do?

​Why are we making this change?

​End-user info is no longer shared between connections

​🗓️ Timeline

​🧐 Am I impacted?

​💡 What should I do?

​Action payload output limit

​🗓️ Timeline

​🧐 Am I impacted?

​💡 What should I do?

​Deprecation of /connection endpoints

​🗓️ Timeline

​🧐 Am I impacted?

​💡 What should I do?

​Migrating to POST /connections

​Deprecation of nango.yaml configuration file

​🗓️ Timeline

​🧐 Am I impacted?

​💡 What should I do?

Sync cache: new data retention policies

✨ What’s changing

Retention lifecycle

🗓️ Timeline

🧐 Am I impacted?

💡 What should I do?

Why are we making this change?

New HMAC-based webhook signature header

🗓️ Timeline

🧐 Am I impacted?

💡 What should I do?

Why are we making this change?

Behavior change of webhooks from Nango to your app

🗓️ Timeline

🧐 Am I impacted?

💡 What should I do?

Why are we making this change?

Function custom logs won’t be ingested by default for remote environments

🗓️ Timeline

🧐 Am I impacted?

💡 What should I do?

Why are we making this change?

End-user info is no longer shared between connections

🗓️ Timeline

🧐 Am I impacted?

💡 What should I do?

Action payload output limit

🗓️ Timeline

🧐 Am I impacted?

💡 What should I do?

Deprecation of `/connection` endpoints

🗓️ Timeline

🧐 Am I impacted?

💡 What should I do?

Migrating to `POST /connections`

Deprecation of `nango.yaml` configuration file

🗓️ Timeline

🧐 Am I impacted?

💡 What should I do?