Monitoring Your Integration

Once your Virtuous integration is running, WeGive provides two tools for keeping an eye on sync health: Integration Logs and Integration Locks. This article explains how to use both to make sure your data is flowing correctly and how to catch issues early.

Integration Logs

Integration Logs are your primary tool for seeing what's happening with your sync. Every time WeGive pushes data to Virtuous or pulls data from Virtuous, a log entry is created.

To access your logs, navigate to Data > Integration Logs in your WeGive dashboard.

Types of Log Entries

Pull Logs track when WeGive retrieves data from Virtuous. This happens automatically every 15 minutes. You'll see entries labeled as "pull" for incremental syncs (changes since last sync) or "pull-all" for full syncs. Pull logs may also be broken down by data type, such as pull_donors or pull_transactions.

Push Logs track when WeGive sends data to Virtuous. These are created in real time as records are created or updated in WeGive. You'll see entries labeled as "create" for new records or "update" for changes to existing records.

Error Logs appear when a sync operation fails. These include the error message from Virtuous's API, which is usually the fastest way to understand what went wrong.

What Each Log Entry Shows

Every log entry includes the data type being synced (donor, transaction, etc.), the specific record ID, the action performed, the status of the operation, and when it happened.

Click Details on any entry to see the full picture, including the JSON payload that was sent, the response from Virtuous, and any error messages.

Log Statuses

Filtering Your Logs

Use the filters at the top of the Integration Logs page to narrow down what you're looking at. You can filter by data type, action (create, update, pull), status, and date range. If you're troubleshooting a specific record, search by the record's ID to see its full sync history.

Downloading Detailed Logs

For pull operations, WeGive generates downloadable log files with more granular detail than what's shown in the dashboard. Look for the Download Log option in the File column. These files contain specifics about API calls, data transformations, and individual record processing results.

Integration Locks

Integration Locks are records that have failed to sync three times in a row. After the third failure, WeGive stops retrying automatically and moves the record to Integration Locks so you can investigate and fix the issue before it tries again.

To view your locks, navigate to Data > Integration Locks.

Why Locks Exist

Without locks, a record with a persistent error (like a duplicate email conflict or a missing required field in Virtuous) would retry indefinitely every 15 minutes and never succeed. Locks prevent this infinite loop and flag the problem for your attention.

Reading Your Locks

Each locked record shows which record failed, what type of data it is, and the error message from the most recent failure. The error message is the most important piece. It tells you exactly what Virtuous rejected and why.

Common error patterns include duplicate email conflicts, missing contact matches, invalid field values, and API permission issues.

Clearing Locks

Once you've identified and fixed the underlying issue, clear the lock so WeGive can retry the sync:

1. Go to Data > Integration Locks

2. Select the locked record(s) you want to clear

3. Click Archive

After archiving, you don't need to manually trigger a resync. WeGive will automatically retry the record during the next integration cycle (within 15 minutes). If the underlying issue is resolved, the record will sync successfully. If the same error occurs, it will lock again after three more failures.

Important: Always fix the root cause before clearing a lock. If you clear the lock without resolving the issue, the record will just fail three more times and lock again.

What to Monitor Regularly

After initial setup: Check your Integration Logs daily for the first week to make sure data is flowing in both directions without errors.

Ongoing: Check Integration Locks weekly. A small number of locks is normal, but a growing list usually means there's a systematic issue that needs attention, like a configuration change in Virtuous or a batch of duplicate emails.

After bulk changes: If you make large updates in either WeGive or Virtuous (bulk imports, field changes, data cleanup), check your logs shortly after to make sure the sync handled everything correctly.

For help diagnosing specific error messages, see How to Diagnose Integration Issues and the individual troubleshooting articles.