​

Overview

Nango sends webhook notifications to your backend in different cases:

• Sync webhook: new data from syncs is available (guide)
• Authorization webhook: an authorization flow completes (guide)
• External API webhook forwarding: an external API webhook is forwarded to your app (guide)

​

Nango webhook settings

Settings related to Nango webhooks can be found in the Environment Settings tab of the Nango UI. It lets you specify webhook URLs as well as the types of webhooks you wish to receive. We advise to enable all webhooks by default and filter for specific webhook types in your codebase.

​

Technical details

Nango retries (with exponential backoff) webhooks with non-2xx responses.

Webhooks from Nango are POST requests with the following JSON body:

{
    "type": "auth",
    "operation": "creation",
    "connectionId": "<CONNECTION-ID>",
    ... // Payload specific to the webhook type/operation.
}

​

Nango webhook verification

Validate webhook provenance by looking at the X-Nango-Signature header.

It’s a SHA-256 hash generated using the secret key found in the Environment Settings in the Nango UI.

The webhook signature can be generated with the following code:

• Node SDK
• Javascript/Typescript
• Python
• Java
• Ruby
• Go
• Rust
• PHP

async (req, res) => {
    const signature = req.headers['x-nango-signature'];
    const isValid = nango.verifyWebhookSignature(signature, req.body);
}

Only accept a webhook if the X-Nango-Signature header value matches the webhook signature.