To process webhooks coming from external APIs (not from Nango), see Process external webhooks. To forward external API webhooks through Nango to your app, see Webhook forwarding.
Set up webhooks from Nango
Webhook settings in Nango are specific to each environment.
- Set up a
POSTendpoint in your app to receive the Nango webhooks - Input the endpointβs URL in your Environment Settings, under Webhook URLs (direct link for your dev environment)
- Implement verify incoming webhooks to ensure sure only authentic Nango webhooks are processed
- Implement processing logic for each webhook type from Nango you want to handle
- Make sure your processing logic handles the webhooks you have enabled in the environment settings
Override webhook URLs per connection
A single connection can override the environmentβs webhook URLs with its own URL. The connection still receives all the same webhook types, with the same signing, retries, and logs. When this override is set, the connectionβs webhooks are sent only to that URL β the environmentβs primary and secondary webhook URLs are both bypassed for that connection. It does not add a third destination. Setwebhook_url_override when creating a connect session. It applies to the connection created by that session:
- Node
- cURL
webhook_url_override from the Create connection flow in the Nango dashboard, under the connectionβs advanced configuration.
webhook_url_override is set by the trusted backend that creates the connect session. A webhook_url passed to nango.auth() params from the client is ignored.Verifying webhooks from Nango
Validate webhooks from Nango by looking at theX-Nango-Hmac-Sha256 header.
Itβs an HMAC-SHA256 hash of the webhook payload, using the webhook signing key found in Environment Settings > Webhooks > Signing key in the Nango UI.
The webhook signature can be verified with the following code:
- Node SDK
- JavaScript/TypeScript
- Python
- Java
- Ruby
- Go
- Rust
- PHP
Pass the webhook signing key as
webhookSigningKey so a single client can make API calls with the API key and verify webhooks with the signing key. webhookSigningKey falls back to secretKey when omitted.X-Nango-Hmac-Sha256 header value matches the webhook signature.
Types of Nango webhooks
All webhooks from Nango are POST requests. The exact webhook type definitions can be found here.Auth webhooks
New connection webhooks have"type": "auth" and "operation": "creation". They are sent after a connection has been successfully created.
Payload received following a connection creation:
authMode values can be found here. The authMode value depends on the provider value.
All operation values are:
creation: a new connection has been createdoverride: a connection has been re-authorizedrefresh: an OAuth connectionβs access token has failed to refresh
Webhooks are only sent for certain connection creation errors. For example, during the OAuth flow, some errors are reported locally in the OAuth modal by the external API. Since Nango does not receive these errors, it cannot trigger a webhook for them.
Sync webhooks
Sync webhooks are sent when a sync function execution finishes, whether successful or not. Payload received following a successful sync execution:modifiedAfter is an ISO-8601 timestamp marking the start of the last run. To read the changed records, use cursor-based fetching as described in Records cache β Cursors and sync progress.
Distinguishing full vs incremental syncs: use checkpoints instead of the deprecated syncType field. checkpoints.from/checkpoints.to are checkpoint objects (Record<string, string | number | boolean>) as saved by the sync function via saveCheckpoint() β not strings β and either can be null. The checkpoints field itself can also be missing or null, so guard against that before reading nested fields:
checkpointsis missing/null, orcheckpoints.from === nullβ the run started with no prior state. This happens on the first run, after a manual reset, or when the sync explicitly cleared its checkpoint. Treat this as a full sync and overwrite your data.checkpoints.fromis a non-null checkpoint object β the run continued from a previously saved checkpoint. This is an incremental sync; merge the new records into your existing data.- Webhook-triggered runs (deprecated
syncType: "WEBHOOK"): always treat these as incremental merges, regardless ofcheckpoints.from. A webhook-triggered run processes a single incoming external event on top of already-synced data β it never represents a full resync.
responseResults would be:
External webhook forwarding
Forwarded external webhooks use the same webhook URLs, signing, retries, and logs as other Nango webhooks. See Webhook forwarding for setup, routing behavior, and payload shapes.Webhook retries & debugging
Nango retries each webhook with non-2xx responses 2 times with exponential backoff (starting delay: 100ms, time multiple: 2, view details in the code). Webhooks time out after 20 seconds. Each webhook attempt is logged in Nangoβs logs. You can also use the OpenTelemetry exporter to monitor Nango webhooks in your own observability stack.Related guides
- Webhook forwarding - forward external provider webhooks through Nango.
- Webhook functions - process provider webhooks inside Nango.
- Event functions - react to connection lifecycle events.
- Observability - monitor webhook operations and retries.