Real-time syncs with webhooks

​

What is a real-time sync

• The webhook triggers the execution of a Nango sync script
• The script extracts data from the webhook and optionally fetches additional data from the external API
• The modified data is stored in the Nango cache

​

Webhooks & periodic polling

​

Near real-time syncing

​

Implement a real-time sync

​

Step 1 — Setup prerequisites

• Webhooks from the external API enabled. Follow Webhook functions.
• A sync function for the object you want to sync. See Sync functions.

​

Step 2 — Enable webhooks processing

export default createSync({
  exec: async (nango) => {
        // Use for periodic polling.
  },

  webhookSubscriptions: ['contact.propertyChange'], // Webhook event type to listen to

  // Webhook handler
  onWebhook: async (nango, payload) => {
    if (payload.subscriptionType === 'contact.propertyChange') {
      const updatedObject = {
        id: payload.objectId,
        [payload.propertyName]: payload.propertyValue
      };

      // Use nango.batchSave() or nango.batchUpdate() to save/update records.
    }
  }
});

​

Sync concurrency considerations

export default createSync({
  exec: async (nango) => {
    // Don't overwrite records that were modified after this batch was fetched
    await nango.setMergingStrategy({ strategy: 'ignore_if_modified_after' }, 'Contact');

    const contacts: Contact[] = [];
    await nango.batchSave(contacts, 'Contact');
  }
});

• override (default) — applies updates regardless of last modification time. May overwrite real-time webhook updates with older polled data.
• ignore_if_modified_after — preserves records that were modified after the current batch was fetched. Recommended when you combine polling with webhooks.

​

Related guides

• Webhook functions - process external API webhooks in Nango.
• Webhook forwarding - forward provider webhooks to your app.
• Sync functions - keep a polling sync as reconciliation.
• Webhooks from Nango - consume sync completion notifications.