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

// POST Endpoint
app.post('/webhook', (req, res) => {
    const response: NangoSyncWebhookBody = req.body;
    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