Webhooks in Detail

Gain a deeper understanding of Webhooks.

iDonate uses Webhooks in order to communicate transaction data to other services. The general concept is that each time a certain event occurs, the corresponding data is then sent to the Targeted URL as a JSON Object (also known as a Payload).

This provides an extensibility layer that allows for Transaction Data synchronization that does not require manual updates of either your Organization’s iDonate Back Office nor your Organization’s CRM of choice.

Event Subscriptions

Each Webhook requires you subscribe to certain Events depending on your Organization’s intended functionality of said Webhook.

Each time a Subscribed Event occurs, that data set is sent to the Targeted URL that can accept the incoming JSON Payload, such as an API Endpoint. From there, it is up to the service to parse that data.

There are a number of Events that you can subscribe to via Webhook. While the titles of these Events are intended to be intuitive, for those uninitiated in the iDonate Platform, however, there may be subtle nuances that require explanation.

In this portion of the guide, we’ll break these Events into archetypes so there is a level of flow and relation between these Events in an aim to ease understanding.

Advocacy Events

First and foremost, what is an Advocate in iDonate? An advocate is a type of donor, who, instead of donating directly to your Organization, gives to - or advocates for - an individual’s Fundraiser Program on behalf of your Organization by way of Peer-to-Peer Fundraiser in iDonate.

So, all things considered, Advocates are still donors, just a very special type of donor that your Organization may or may not want to catalog differently than the more common, yet just as appreciated donor type.

So, a way that you can more easily digest and understand the data that iDonate will be sharing with your Organization’s CRM as it relates to Advocacy Events is to equate these records and fields to all things Peer-to-Peer and Fundraisers.

Event Description Organization Initiated
Advocacy Program Created Peer-to-Peer Program Created Yes
Advocacy Program Updated Peer-to-Peer Program Updated Yes
Advocacy Program Archived Peer-to-Peer Program Archived Yes
Advocacy Program Unarchived Peer-to-Peer Program Unarchived Yes
Advocacy Program Deleted Peer-to-Peer Program Deleted (1) Yes (1)
Advocacy Program Published Peer-to-Peer Program Published (2) Yes
Advocacy Program Unpublished Peer-to-Peer Program Unpublished (2) Yes
Advocacy Program Expired Peer-to-Peer Program has reached set End Date Yes (3)
Advocacy Team Created Fundraising Individuals created a Team Open (4)
Advocacy Team Updated Team attributes updated or changed Open (4)
Advoacy Team Member Joined A Fundraising individual has joined a Team Open (4)
Advocacy Team Member Left A Fundraising Individual has left a Team No
Advocacy Team Member Milestone Reached A Team member has met a set Dollar Amount Goal No
  1. Deleting items and data in iDonate’s database comes with a great deal of nuance due to Tax Laws regarding Non-Profits. An Organization can request data or items be deleted, however, ultimate discretion is case-by-case.
  2. P2P Programs must be Published before they and any related forms, links, Hubs and any additional and related attributes are viewable outside of iDonate’s GMS Back Office.
  3. When creating a P2P Program an Organization can set an End Date (Expiration Date). If the Organization ops to set an End Date, no additional action is needed to Initiate the expiration of said Program, however, if no End Date (Expiration Date) is set by the Organization, a manual process is needed to end said Program.
  4. When the Organization is creating a P2P Program, they are allowed to set Team Rules and Team Settings.

Donor Events

For most iDonate users, the term Donor is fairly well understood. For the sake of clarity however, iDonate classifies an individual that gives a gift, regardless of type (cash, non-cash), directly to an Organization using an iDonate Giving Form as a Donor.

Many Events that can be subscribed to will pass Donor Fields in their payloads, however, a few Events will trigger a Webhook without a Transaction or Gift record. This section will outline and provide context to these Events.

Example: Phillip has updated his address using the Donor Self Serve portal. This, along with most actions taken in the Donor Self Serve portal will trigger Donor Related Events.

Event Description Org. Initiated
Donor Contact Updated Anytime a Donor attribute is updated Open
Donor Payment Method Updated A Donor has updated their Payment Methods (1) No (1)
Donor Canceled Organization Schedules A Donor has canceled a Recurring Donation Schedule to this Org No (2)
Donor Requested Organization Giving History A Donor has requested a historical record of their gift transactions for this Org No
Donor Contact Update Requested This is a Virtuous Specific Function Yes
  1. At no point will iDonate update, edit, or otherwise alter a Donor’s Payment Method nor will iDonate recommend an Organization do so. Should a Donor need to make changes to their Payment Method, they should visit and login to their Donor Self Serve portal.
  2. While the donor can and should utilize the Donor Self Serve Portal to complete this action, the Organization can reach out to support@idonate.com and submit a request to cancel a recurring donation.

"Event" Event

So this one can get a little confusing if we are not strict and clear about what a Transaction Event and an Event Transaction is. In the iDonate GMS Back Office your Organization can create a Ticketed Event for whatever fits your Organization’s needs.

When we say Ticketed Event think Golf Tourney, Charity Auction, Gala, etc etc. These Ticketed Events will create an Event Transaction which will trigger a Transaction Event- the thing your Organization will subscribe to.

The only Event Transaction to subscribe to for Ticketed Events is Event Attendee Registered. This Transaction Event will send a payload containing only the fields relating to the Attendee, represented as “guest_{x}” fields in the payload schema, and Ticketed Event specific fields.

As this is the only Transaction Event your Organization can subscribe to related to Ticketed Events, no table has been included.

Recurring Events

Recurring or Scheduled Donation Events are specific to gifts that are scheduled to occur more than once. Please Note: Depending on your organization’s CRM of choice, recurring schedules may behave differently. Visit our Salesforce or Virtuous documentation for a thorough breakdown of how recurring gifts in iDonate transfer to these CRMs.

Event Description Org. Initiated
Recurring Donation Schedule Created A Donor has created a recurring gift schedule No
Recurring Donation Schedule Updated A Donor has updated a recurring gift schedule in DSS No
Recurring Donation Schedule Canceled A Donor has canceled a recurring gift schedule in DSS No
Recurring Donation Schedule Donor Updated Requested This is a Virtuous Specific Function No

Transaction Events

Transaction Events are easily definable and understandable Events available for Webhook subscription. However, it is important to understand that Transaction Events are incredibly broad compared to our other Event archetypes.

Whereas Recurring or P2P Events pertain to very specific cross sections of the iDonate giving platform, relating to their titular Channels within iDonate. To improve focus, flow, and ease of understanding Transaction Events have been broken into sub-groups with additional context provided as necessary.

Transaction Set Events

Transaction Set Events are engineered to provide an important functionality for CRMs that support multi-designation functionality.

To know if Transaction Set Events are right for your Organization and CRM of choice, it’s important that you understand this concept and its behavior fully.

A multi-designation transaction occurs when a donor gives a gift with two or more Designations selected. While this process is simple for the Donor, what happens behind the scenes involves numerous moving parts.

When a multi-designation transaction occurs, a transaction record is created for each designation and the Transaction Set event subset will capture every aspect of this process into a (Transaction) Set.

Example 1: Transaction Set Created (Salesforce and CRMs that support Multi-Designation): $20 Dollar Donation with one designation would appear as one Opportunity with one Allocation under the Contact. $20 Dollar Donation with 4 designations would appear as one Opportunity with four allocations under the Contact. In both instances a single JSON payload is fired to the targeted Webhook URL.

Event Description Org. Initiated
Transaction Set Created Anytime Donor gives a gift, whether single or multi-designation and regardless of channel. A catch-all Event Subscription. No
Transaction Set Changed Anytime a gift is changed in any way. Open

Transaction Completed Event

The Transaction Completed Event function similarly to Transaction Set Events except when considering multi-designation transactions. Whereas Transaction Set Events will capture all aspects of a transaction in a single payload, Transaction Completed capture each designation as a single payload. This is important is your Organization’s CRM of choice does not support multi-designation allocations.

Example 2: Transaction Completed: (Virtuous and CRMs that do not support Multi-Designation): $20 Dollar Donation with one designation would appear as one Gift with one Project under the Contact. $20 Dollar Donation with four designations would appear as four Gifts with one Project under the Contact. In the first instance a single payload is fired and in the second instance, four payloads are fired to the targeted Webhook URL.

Event Description Org. Initiated
Transaction Completed A Donor gives a gift, regardless of channel. If a multi-designation gift, see above. No

Non-Cash Transaction Events

A feature of the iDonate Digital Giving Platform is Non-Cash Gifting. This allows your Organization to process donations in various non-cash forms, think vehicles, jewelry, stocks, and much much more. Because of the unique processes of processing gifts such as those mentioned above, similarly unique Subscription Events have been engineered to track and catalog these transactions.

If you take into account the steps required to convert a car or a stock donation into dollars and cents useful to your Organization and its causes, the purposes of these Events begin to speak for themselves. Please Note: For the sake of focus and flow and ease understanding, all Event Descriptions will be in the context of a Vehicle donation as this process covers all non-Cash Event Subscriptions.

Event Description Org. Initiated
Transaction Created A Donor has submitted a Non-Cash Gift Donation. (1) No
Transaction Updated A Non-Cash Gift Transaction’s status has been updated. (1) No
Transaction Pending A Non-Cash Gift Transaction is in a Pending status. (1) No
Transaction Approved A Non-Cash Gift Donation has been approved by iDonate’s Non-Cash Gift processors. (1) No
Transaction Sold A Non-Cash Gift Donation’s status has been marked as “Sold” by iDonate. (1) No
  1. For a full process break down of the standards of iDonate’s Non-Cash processing please contact idcfsupport@idonate.com or call (877)-897-4273.

Refund and Canceled Transaction Events

Refunded and Canceled Transaction Events will apply to all transactions, regardless of the origin or subtype of the transaction in question. Again, these are relatively self explanatory and are engineered to trigger anytime a transaction is Canceled or Refunded, however it is important to understand the difference between a Canceled Transaction and a Refunded Transaction.

Generally, the only transactions that will trigger a Cancelation are those submitted via ACH (echeck) or Non-Cash Gifts. Refunded Transactions are generally those that have already processed, such as gifts processed via Credit or Debit Card or via digital wallets like Apple Pay, Google Pay, and PayPal.

Event Description Org. Initiated
Transaction Canceled A donor's gift has been canceled Yes (1)
  A donor's gift has been refunded Yes (1)
  1. All Refunds and Cancellations are initiated by your Organization. You have the ability to do both via your iDonate GMS Back Office, however, should you require assistance with this process contact support@idonate.com.

P2P (New) Events

P2P is iDonate’s revamp of our Peer-to-Peer Functionality and Interface. This feature update has simplified and streamlined much of the functionality, as well as given additional tools for your Organization and your donors and fundraisers as well.

Despite this update, many of the Event Subscriptions are quite similar to Advocacy Events listed earlier in this document.

Event Description Org. Initiated
P2P Program Created A P2P Fundraising Program has been created Yes
P2P Program Updated A P2P Fundraising Program has been updated Yes
P2P Program Archived A P2P Fundraising Program has been Archived Yes (1)
P2P Fundraiser Created A P2P Fundraiser (Individual) has been created Yes
P2P Fundraiser Updated A P2P Fundraiser’s (Individual) User has been updated No (2)
P2P Fundraiser Archived A P2P Fundraiser (Individual) User has been archived Yes (1)
P2P Fundraiser Update Posted A P2P Fundraiser (Individual) has posted a profile update No (2)
P2P Fundraiser Milestone Reached A P2P Fundraiser’s (Individual) fundraising goal or milestone (dollar amount) has been reached

No (2)

  1. Your Organization can Archive P2P Programs and Fundraisers in your iDonate GMS Back Office. In you require assistance in this process contact support@idonate.com.
  2. When creating P2P Programs, your Organization can configure settings allowing or disallowing various Fundraiser options.