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.

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.

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. Donors can utilize the Donor Self-Service (DSS) Portal to cancel their recurring gift. iDonate users can Cancel a Recurring Schedule.

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

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.

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.

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.

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.

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.

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.