Integration Nuances

Pipeline limit on HubSpot free tier

HubSpot’s free tier permits only one Deal pipeline. When WeGive provisions on a free account it cannot create both the Donations and Recurring Donations pipelines.

Behavior on the free tier:

WeGive will detect the limit and use the single existing pipeline.
Both one-time and recurring deals are placed in that pipeline; status mapping still works.
Upgrade your HubSpot tier and click Provision again to gain the dedicated Recurring Donations pipeline.

Rate limiting

WeGive uses HubSpot’s batch endpoints (up to 100 records per call) and respects the Retry-After header. If you hit a 429, WeGive backs off with exponential delays of 10s, 20s, and 30s, then resumes. No action is required from you.

Deduplication

On push, WeGive places a 600-second lock per model (hubspot_push_{model_id}) so concurrent edits don’t generate duplicate creates.
If a 409 Conflict returns from HubSpot (contact already exists with that email), WeGive extracts the existing HubSpot ID from the error response and links it to the WeGive record.
On pull, donors are matched in this order: hubspot_id → wegive_id (custom property) → email. Matching by email is the fallback so HubSpot users created outside WeGive can still link cleanly.

Currency conversion

All financial fields are stored in WeGive as cents. They are divided by 100 before being pushed to HubSpot, so $50.00 appears as 50 on the deal record, not 5000.

ACH handling

By default, ACH transactions in processing status sync to HubSpot as Attempted. If your team treats ACH as effectively cleared the moment it’s initiated, enable send_processing_ach_as_success in Configuration Options — those deals will push as Success and update to Failed if the ACH later fails.

Webhooks: deletions, not changes

WeGive subscribes to HubSpot webhooks for deletion events only (contact.deletion, contact.privacyDeletion, company.deletion, deal.deletion).

When a deletion is received:

Contact / company / deal deletions in HubSpot do not delete WeGive records. WeGive is source of truth for donors.
WeGive clears the hubspot_id linkage on the corresponding record so the next push can re-create the record cleanly.
The single exception is contact.privacyDeletion (GDPR), which does delete the WeGive donor in compliance with the customer’s privacy obligations.

Webhook signatures are validated with HMAC-SHA256 (v3); requests with a timestamp older than 5 minutes are rejected.

Pipeline stage status mapping

Donations pipeline

WeGive transaction status	HubSpot deal stage
`success`	Success
`processing`, `attempted`	Attempted
`failed`, `cancelled`	Failed

Recurring Donations pipeline

WeGive scheduled donation status	HubSpot deal stage
`active`	Active
`paused`	Paused
`cancelled`	Cancelled
`ended`	Ended
`in_arrears`	In Arrears
`missing`	Missing
`archived`	Archived

Marketing Contacts

WeGive does not distinguish between HubSpot Marketing Contacts and regular Contacts. All donors push as standard Contacts; marketing-contact status is controlled inside HubSpot.

Deal naming

WeGive uses a consistent format for the deal name so it’s scannable in HubSpot:

One-time: {Donor Name} – ${Amount} – {Fund Name}
Recurring: {Donor Name} – ${Amount}/{Frequency} – {Fund Name}

If no fund is set on the gift, the fund segment is omitted.

Associations require both IDs

A deal will only associate to a contact or company once both records exist in HubSpot. If you see deals with no associated contact:

Check that the donor has a populated hubspot_id in WeGive (push completed).
Re-run the next sync — the deal will associate on its next push.

This is intentional — it avoids creating orphaned deals during the brief window between pushing a transaction and its donor.