Skip to main content

​
Setting up an integration

This article walks you through connecting any integration in WeGive, then covers the specifics for each of WeGive’s currently supported integrations. Most integrations follow one of two connection 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.

​
What integrations does WeGive support?

WeGive currently supports sync with the following CRMs and tools:
  • Salesforce NPSP
  • Salesforce Nonprofit Cloud (NPC)
  • HubSpot
  • DonorPerfect
  • Bloomerang
  • Raiser’s Edge (via Blackbaud)
  • Virtuous
  • Neon
  • Planning Center
  • Church Community Builder (CCB)
  • DonorDirect
  • Double the Donation
  • DocuSign
  • Zapier
  • Webhooks (direct event subscriptions to your own endpoints)
  • Siebel CRM
Each integration has its own setup screen because each system authenticates differently and exposes different objects (donors, transactions, funds, campaigns, etc.).

​
Before you begin

You’ll need:
  • A dashboard user with permission to view/manage integrations (the integrations.view permission). This is 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.
Environments must match. A WeGive Sandbox account can only connect to your CRM’s sandbox environment; WeGive Production can only connect to your CRM’s production environment. Mismatched environments will fail at the connection-test step.

​
Step 1: Open the Integrations page

From your dashboard, go to Settings → Integrations → 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. Bloomerang specifically requires a Default Fund ID (go to Bloomerang’s Settings → Custom Data → Funds to find it) — Bloomerang requires every transaction to have a fund ID, so if this is missing or wrong, transactions will not sync. Neon requires both an Org ID and an API Key, both from Neon’s Settings → Integrations → API Keys page. Make sure you’re using the credentials that match your WeGive environment — a Neon Production key won’t work in WeGive Sandbox, and vice versa.

​
If it’s an OAuth integration

Examples: Salesforce (NPSP and Nonprofit Cloud), HubSpot, Planning Center, Raiser’s Edge, 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. Salesforce (NPSP and Nonprofit Cloud) uses this same OAuth flow — a Connected App (or External Client App) in your Salesforce org producing a Client ID and Client Secret, followed by an authorization redirect. The current dashboard only exposes this OAuth path; there is no username/password field anywhere in the Salesforce setup screen. (The backend data model still has legacy username/password columns from an older password-grant connection method, but no current UI writes to them — don’t be surprised if you see them mentioned in older internal notes.) After connecting:
  • Configure pull/push toggles for donors, households, companies, campaigns, funds, transactions, and pledges.
  • Set your Stage Name mappings (e.g., which Opportunity stage represents a successful donation, a refund, and a failed payment).
WeGive account environment must match Salesforce environment — Sandbox WeGive accounts go with Salesforce sandbox orgs; Production goes with Production.

​
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.

​
Configure field mappings

Once an integration is connected, you can set up custom field mappings under the integration’s settings page. Mappings let you:
  • Map a WeGive field to a CRM field.
  • Choose direction: import only, export only, or both.
  • Set a literal value (e.g., always send a fixed value to your CRM).
  • Decide whether the field updates on creation only, or every time the record syncs.
Custom field mappings are organized by object type — donors, households, companies, campaigns, funds, transactions, recurring plans, and pledges — depending on which integration you’re using.

​
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 (Settings → Integrations → Integration Logs) 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, or required credentials (Client ID/Secret) weren’t saved yet. Check that the Client ID and Client Secret are correct and saved, 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. A record won’t sync after several attempts. If a single record fails to sync repeatedly, WeGive moves it to Integration Locks (Settings → Integrations) to prevent infinite retries. Find it there, read the error message, fix the issue (missing field, validation rule, permission), and unlock the record to let it retry. 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.

​
Best practices

  • Test in sandbox first whenever possible.
  • Don’t disconnect and reconnect an integration to “reset” it — this can create duplicate records. If you’re stuck, reach out to support before disconnecting.
  • After changing field mappings, run a small test sync on a single record before re-running historical sync.
  • Review Integration Logs weekly during the first month of a new integration to catch validation rules or field-level permission issues early.

​
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:
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. Salesforce’s OAuth strategy (SalesforceOauth) specifically uses PKCE (Proof Key for Code Exchange): a code verifier/challenge pair plus a CSRF state token are generated and stored on the integration record before redirecting to Salesforce’s authorization URL. The SalesforceIntegration model also retains a legacy username/password OAuth2 password-grant path (testLegacyConnection(), used when oauth_enabled is false), but no current dashboard view exposes those fields for input — they’re a backend-only remnant, not something a customer or admin can set today.

​
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 syncAll boolean parameter passed to 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