Receive webhooks from Nango

Step-by-step guide on how to receive webhooks from Nango.

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

{
    "type": "sync",
    "connectionId": "<string>",
    "providerConfigKey": "<string>",
    "syncName": "<string>",
    "model": "<string>",
    "responseResults": { "<DataModel>": { "added": 123, "updated": 123, "deleted": 123 } },
    "syncType": "INITIAL" | "INCREMENTAL",
    "modifiedAfter": "<timestamp>"
}

Authorization webhook

Authorization webhooks must be enabled in the Environment Settings tab of the Nango UI.

{
    "type": "auth",
    "connectionId": "<string>",
    "authMode": "OAUTH2|",
    "providerConfigKey": "<string>",
    "provider": "<string>",
    "environment": "prod|dev",
    "success": boolean,
    "operation": "creation|override|unknown",
    "error": "<string|undefined>"
}

Webhook Forwarding

Learn how to receive webhooks from external APIs (step-by-step guide).

{
   "from": "hubspot",
   "type": "forward",
   "payload": ... // Raw payload from Hubspot webhook
}

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.