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
• 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",
    "modifiedAfter": "<timestamp>"
}

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.