Setting up an integration

This article walks you through connecting any integration in WeGive. Most integrations follow one of two patterns — API key or OAuth — so once you've set one up, the rest will feel familiar.

Before you start, see Available integrations to find the one you need. For background on what integrations do, see Integrations overview.

Before you begin

You'll need:

• Admin access to WeGive. Integrations are usually restricted to admin-level users.

• Admin access to the system you're connecting to. You'll need to generate an API key, register an app, or grant OAuth access on that side, all of which typically require admin permissions there too.

• About 15–30 minutes. OAuth integrations move quickly. API-key integrations that involve generating credentials in another system can take longer if it's your first time in that system.

Step 1: Open the Integrations page

From your dashboard sidebar, go to Integrations. You'll see a tile for each integration WeGive supports. Click the tile for the integration you want to set up.

Step 2: Connect

What you see next depends on whether the integration uses an API key or OAuth.

If it's an API-key integration

Examples: Bloomerang, Virtuous, Neon, DonorPerfect.

1. In a separate tab, log in to the connected system and generate an API key. Each system has its own way of doing this — refer to that system's documentation if you need help finding the API key screen.

2. Copy the API key.

3. Back in WeGive, paste the key into the API key field on the integration's settings page.

4. If the integration asks for additional identifiers (Bloomerang asks for a default fund ID, Neon asks for an org ID), fill those in too.

5. Click Save to save the connection settings.

If the key is valid, you'll see a confirmation. If something's wrong (typo, expired key, insufficient permissions on the key), you'll see an error message describing what failed.

If it's an OAuth integration

Examples: Salesforce, Raiser's Edge, Planning Center, DocuSign.

1. In the connected system's developer or app settings area, register WeGive as a connected app. This produces a Client ID and Client Secret, and sometimes a Subscription Key (Raiser's Edge in particular). Each system documents this differently — check their developer docs for the right screen.

2. Paste the Client ID, Client Secret, and any other required fields into the integration's settings page in WeGive. Save.

3. Click the OAuth button (label varies by integration, often Connect or Authorize). A new tab opens to the connected system's login page.

4. Log in to the connected system and grant WeGive the requested permissions.

5. The connected system redirects back to WeGive. Return to the WeGive tab.

6. Refresh the integration's status. You should see it now shows as connected.

If you get an error during OAuth, the most common causes are: incorrect Client ID/Secret, the redirect URI on the connected system's app config doesn't match what WeGive expects, or the user account you authorized with doesn't have permission to grant the scopes WeGive requested.

Step 3: Configure your sync

Once connected, you'll see sync configuration options. For CRM integrations these are typically toggles for each direction and record type, like:

• Push donors (WeGive → connected system)

• Pull donors (connected system → WeGive)

• Push funds / Pull funds

• Push transactions / Pull transactions

Turn on only the directions you want. A common setup is to treat your CRM as the system of record for donors and funds (pull from CRM into WeGive), while pushing transactions WeGive captures back into the CRM. But every organization is different — pick the directions that match your operations.

Click Save when you're done. Sync configuration saves separately from the connection settings, so you can change sync rules later without re-authenticating.

Step 4: Run an initial sync

After saving, you can run a manual sync to backfill data. Most integrations offer two options:

• Sync all — pulls/pushes the full dataset. Use this for the very first sync.

• Sync since last update — only syncs records changed since the last sync. This runs automatically going forward; you'd only run it manually to force a refresh.

Initial syncs can take a while if you have a lot of historical data. You can leave the page; the sync runs in the background.

Step 5: Verify

A few checks to confirm the integration is working as expected:

• Look at the last synced timestamp on the integration's settings page — it should update after the manual sync.

• Spot-check a few records in the connected system to confirm they reflect what's in WeGive (or vice versa, depending on direction).

• Check the Integration Logs page for any errors during the initial sync.

If everything looks right, you're done. The integration will continue to sync on its own going forward.

Troubleshooting

"Failed to save connection settings." Usually means an API key is wrong, expired, or doesn't have the required permissions on the other system's side. Regenerate the key and try again.

"Failed to initiate OAuth flow." Means WeGive couldn't reach the connected system's authorization endpoint. Check that the Client ID and Client Secret are correct, and that any required fields (e.g., Subscription Key for Raiser's Edge) are filled in.

OAuth tab opens but throws an error after I authorize. Most often a redirect URI mismatch. The redirect URI registered on the connected system's app needs to match exactly what WeGive uses. Confirm with your CSM or check the connected system's developer guide.

Integration shows as connected, but no records are syncing. Check that you've turned on the right sync toggles and saved. Connection status and sync configuration save separately.

Records are syncing but to the wrong place. For Bloomerang specifically, check the default fund ID. For other CRMs, look for designation or fund mapping in the integration's settings.

I'm seeing duplicates. This usually points to a matching/dedupe setting on the connected system's side. Reach out to support — duplicates are typically resolvable but the fix depends on which system you're using.

If you hit something not covered here, message support with the integration name, what you tried, and any error message you saw. Including a screenshot of the Integration Logs page speeds things up considerably.

For technical users

Connection vs sync are saved independently

Each integration in wegive-dashboard-v2 has two save actions: saveConnectionSettings() (writes credentials only) and saveSyncConfiguration() (writes the sync toggles and any related config like default fund ID). Both hit the same update endpoint on the backend (e.g., PUT /bloomerang-integration) but with different payloads. This means an admin can adjust sync behavior without re-supplying credentials, and rotating an API key doesn't reset sync settings.

OAuth initiate flow

For OAuth integrations, the frontend calls a dedicated initiate endpoint:

POST /<integration>-integration/oauth/initiate

The backend validates that required credentials (Client ID, Secret, etc.) are present, builds the authorization URL using the appropriate OAuth strategy, and returns it. The frontend opens the URL with window.open(url, '_blank', 'noopener,noreferrer') and shows a snackbar telling the admin to complete authorization in the new tab and refresh status.

There is no automatic redirect back to the integration page after OAuth completes — the admin manually returns to WeGive and refreshes the connection status. This is intentional given the new-tab flow; the callback handler updates the stored token server-side, and the frontend reads that updated state on refresh.

Required scopes by integration

Scopes are configured in the OAuth strategy classes on the backend (RaisersEdgeOauth, SalesforceOauth, etc.) and are not user-configurable. If you're registering WeGive as an app on the connected system, you typically don't need to specify scopes there — WeGive requests them at runtime via the authorization URL.

Sync jobs

Sync jobs run asynchronously through the Laravel queue (app/Jobs/). Manual syncs and scheduled syncs use the same job classes, so behavior is consistent. The "Sync all" vs "Sync since last update" distinction is a parameter on the job, not a different code path.

Integration logs

User-visible errors are abbreviated; full error context (HTTP status codes, payloads, stack traces) is written to the integration log table and shown on the Integration Logs page. This is the right place to look when debugging customer-reported sync failures.

Disconnecting

For OAuth integrations, disconnect calls POST /<integration>-integration/oauth/disconnect, which revokes the token on WeGive's side (and where supported, on the connected system's side). For API-key integrations, clearing the API key field and saving accomplishes the same thing.

Where to look in code