Skip to main content
Nango can receive, route, and process webhooks from external APIs on your behalf. You register a single Nango URL with the external API, and Nango handles the rest: identifying the connection the webhook belongs to, verifying signatures, and either forwarding the payload to your app or triggering a function to process it.

​
When to use webhook processing

  • You want real-time notification of changes in an external API
  • You don’t want to build or maintain webhook ingestion infrastructure
  • You need webhooks attributed to specific users (connections) automatically
  • You want to combine webhooks with polling syncs for a reliable real-time data pipeline
Common examples: “contact updated” webhooks from HubSpot or Attio, “new order” webhooks from Shopify triggering a sync run.

​
How webhook routing works

Each integration has a unique Nango webhook URL: 
https://api.nango.dev/webhook/<YOUR-ACCOUNT-UUID>/<INTEGRATION-ID>
For example: 
https://api.nango.dev/webhook/d91981c1-257a-4a42-adb3-a849da15f0dc/hubspot
When a webhook arrives at this URL, Nango:
  1. Identifies the integration from the URL path
  2. Attributes it to a connection using integration-specific routing logic to extract the user identifier from the payload
  3. Verifies the signature to confirm the webhook is genuine
  4. Forwards or processes the webhook based on your configuration
Nango has off-the-shelf webhook support for many popular APIs. Check the Nango webhooks folder for the current list. If the API you need is not listed, request it in the Slack community.

​
Forwarding vs. processing in Nango

You have two options for how Nango handles incoming webhooks — and you can combine them:
Nango forwards the raw webhook payload to your configured webhook endpoint. This is the default behavior and requires no function code.The forwarded payload wraps the original webhook data with connection metadata:
{
    "from": "hubspot",
    "type": "forward",
    "connectionId": "user-123",
    "providerConfigKey": "hubspot",
    "payload": {
        // original webhook body from the external API
    }
}
To disable forwarding, go to Environment Settings → Notification settings → disable Forward webhooks from external APIs.
The webhook triggers a function in Nango. This lets you make additional API requests, transform the data, and save records to the sync cache — before optionally forwarding the processed result to your app.To set this up, follow the real-time syncs guide.

​
Set up webhook processing

1

Configure webhooks from Nango to your app

First, set up a webhook endpoint in your app and add its URL in the Nango dashboard under Environment Settings → Notification settings.This is where Nango will forward processed webhook events.
2

Register the Nango webhook URL with the external API

In the external API’s developer portal, register the Nango webhook URL as the destination for incoming events.Find your Nango webhook URL in the Nango dashboard: Integrations → select an integration → Settings tab.It will look like:
https://api.nango.dev/webhook/<YOUR-ACCOUNT-UUID>/<INTEGRATION-ID>
3

Decide how Nango should handle the webhook

Choose one:
  • Forward to your app — enabled by default, no code required
  • Trigger a sync run — configure a real-time sync to run when a webhook arrives
  • Both — process in Nango and forward the enriched result to your app

​
Verify webhook signatures from Nango

When Nango forwards a webhook to your app, it signs the request so you can verify it came from Nango. Use verifyIncomingWebhookRequest in the Node SDK: 
import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: process.env.NANGO_SECRET_KEY });

app.post('/webhook', (req, res) => {
    const isValid = nango.verifyIncomingWebhookRequest(
        req.rawBody,   // raw HTTP body as a string
        req.headers    // must include 'x-nango-hmac-sha256'
    );

    if (!isValid) {
        return res.status(401).send('Invalid signature');
    }

    const { from, connectionId, providerConfigKey, payload } = req.body;

    // Process the webhook
    console.log(`Webhook from ${from} for connection ${connectionId}`);

    res.status(200).send('OK');
});
Use verifyIncomingWebhookRequest (HMAC-SHA256) rather than the deprecated verifyWebhookSignature. The older method is vulnerable to length-extension attacks.

​
Combine webhooks with polling syncs

For maximum reliability, you can run both a polling sync and a webhook handler that update the same Nango cache. When the external API sends a webhook, it triggers a sync run immediately. The regular polling schedule acts as a fallback to catch anything missed. This gives you real-time updates with the reliability of polling. See the real-time syncs guide for implementation details.

​
Observability

All incoming webhooks create detailed log entries in the Nango dashboard. You can see:
  • The raw webhook payload
  • Which connection it was attributed to
  • Whether it was forwarded, processed, or both
  • Any errors during processing

Build docs developers (and LLMs) love

Get started for freeTalk to us