Nango sends webhooks notifications to your backend in different cases:

  • Sync webhook: new data from syncs is available
  • Authorization webhook: an authorization flow completes (successfully & unsuccessfully)
  • Webhook forwarding: a webhook from an external API is received

To set this up, go to the Environment Settings tab and configure a Webhook URL to which Nango will send notifications.

Webhooks with non-2xx responses are retried with exponential backoff.

Webhooks from Nango are POST requests with the following body:

  • Sync webhook

  • Authorization webhook

  • Webhook Forwarding

    "type": "sync",
    "connectionId": "<string>",
    "providerConfigKey": "<string>",
    "syncName": "<string>",
    "model": "<string>",
    "responseResults": { "<DataModel>": { "added": 123, "updated": 123, "deleted": 123 } },
    "syncType": "INITIAL" | "INCREMENTAL",
    "queryTimeStamp": "<timestamp>", // Null for initial sync runs.

Verify webhooks from Nango

Validate webhook provenance by looking at the X-Nango-Signature header. It’s a SHA-256 hash generated with the secret key found in your settings and with the payload of the request body:

import crypto from 'crypto';

const secretKeyDev = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
const signature = `${secretKeyDev}${JSON.stringify(payload)}`;
const hash = crypto.createHash('sha256').update(signature).digest('hex');

Accept the webhooks if the X-Nango-Signature header value matches the hash.

Questions, problems, feedback? Please reach out in the Slack community.