​
Webhooks from Nango to your app

You can configure Nango to send a webhook to your app every time a sync finishes and new data is available.

To set this up go to Project Settings page and set your webhook receive URL there.

The webhook from Nango is a POST request with the following body:

{
    "connectionId": "<user-id>",              // The connection's ID, as set by you in nango.auth
    "providerConfigKey": "<integration-id>",  // The name of the integration in Nango, e.g. github
    "syncName": "<sync-name>",                // The name of the sync as defined in nango.yaml, e.g. github-tickets
    "model": "<data-model>",                  // The name of the data model, e.g. ticket
    "responseResults": { "<DataModel>": { "added": 123, "updated": 123, "deleted": 123 } }, // The number of new/updated/deleted records, per object type.
    "syncType": "INITIAL" | "INCREMENTAL",   // "Initial" or "incremental" run
    "queryTimeStamp": "2023-05-31T11:46:13.390Z", // Use this with "delta" in getRecords to fetch the data of this sync. Note that this property will be null for the initial sync job.
}

If your sync returns multiple models you may receive multiple webhooks for the same sync run (one for each model).

For full type safety the @nangohq/node package exports a type annotation for the webhook. Example usage:

import express from 'express';
import bodyParser from 'body-parser';
import { NangoSyncWebhookBody } from '@nangohq/node';

const app = express();

// Middleware
app.use(bodyParser.json());

// POST Endpoint
app.post('/webhook', (req, res) => {
    const response: NangoSyncWebhookBody = req.body;
    console.log(response);
    res.status(200).send('Received POST request');
});

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

​
Webhooks from external APIs to Nango

You can handle incoming webhooks from external APIs using Nango:

  • Configure the webhook with your application as you would normally do
  • Write a sync script that returns the data models you want (it can perform additional API requests if needed)
  • Upon webhook reception, trigger the sync script and pass it the webhook payload
ProxyField Mapping