A webhook is like a notification sent from one application to another when something happens. For example, a webhook could be used to update a contact whenever a new address is received, or to add a tag when a donor gives to a certain campaign.
You can use webhooks to be notified about events that happen in your RaiseDonors account. RaiseDonors can send webhook events that notify your application any time a specific event happens from within RaiseDonors. This is especially useful for events—like a new donation, a new recurring donation, a donors information has been updated, etc. Some common applications of webhooks are:
You can register webhook URLs that we will notify any time an event happens in your account. When the event occurs—a successful donation is completed, a recurring donation happened, a donor update his/her account, etc.—RaiseDonors creates an Event object.
This Event object contains all the relevant information about what just happened, including the type of event and the data associated with that event. RaiseDonors then sends the Event object, via an HTTP POST request, to any endpoint URLs that you have defined in your account’s webhook subscription settings. You can have RaiseDonors send a single event to many webhook endpoints. Webhooks are triggered from any activity source in RaiseDonors including:
RaiseDonors supports many webhook types. The naming convention follows the principle of {object} {verb}. To access webhooks from your Raise Donors Dashboard select System Settings then Webhooks. From there, you can create a new webhook by selecting +New Webhook in the upper right corner.
Next, fill in the appropriate fields for the webhook.
The two most common webhook mistakes are providing the wrong URL in the Dashboard's webhooks settings, and not returning a 200 status code from the webhook endpoint.
Receiving Webhooks with an HTTPS Server
You must use an HTTPS URL for your webhook endpoint, RaiseDonors will validate that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate.
Responding to a Webhook
To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, will indicate to RaiseDonors that you did not receive the webhook. This does mean that a URL redirection or a "Not Modified" response will be treated as a failure. RaiseDonors will ignore any other information returned in the request headers or request body. RaiseDonors will wait approximately 60 seconds (max) for a response.
If your endpoint does not successfully receive a webhook for any reason, we will continue trying with the following delayed timeline.
First Attempt
2nd attempt- 1 second delay
3rd attempt- 5 second delay
4th attempt- 10 second delay
5th attempt-25 second delay
Webhooks cannot be manually retried after this time, though you can query for the event to reconcile your data with any missed events. If a webhook fails a total of 10 times within 24 hours, it will be paused automatically.
When viewing a specific event information through the Admin Dashboard, you can check how many times we've attempted to send an event to an endpoint by clicking on that endpoint URL in the webhook details section. This will show you the latest response we received from your endpoint, along with a list of all attempted webhooks and the respective HTTP status codes we received.
Best Practices
If your webhook script performs complex logic, or makes network calls, it's possible that the script would time out before RaiseDonors sees its complete execution or your scripts could generate errors. For that reason, you should follow best practices and have your webhook endpoint immediately acknowledge receipt by returning a 2xx HTTP status code, and then perform the rest of its duties separately.
Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent . One way of doing this is logging the events you've processed, and then not processing already-logged events. Additionally, we recommend verifying webhook signatures to confirm that received events are being sent fromRaiseDonors.
Webhook events are designed to send the notification within milliseconds of the actual event taking place; as close to real-time as possible. However the webhook system is dependent on a queueing system to handle large volumes of data happening at once. In these situations it is possible to see delays in sending the webhook events.
Security
RaiseDonors will include a security token with every event sent to your listening url. You can configure this security token when creating the webhook subscription in RaiseDonors. The field allows you to supply any varchar value you wish. We recommend a minimum of 50 characters to ensure someone can't easily guess the security token. It is your responsibility to ensure the incoming webhook from RaiseDonors includes the security token. It's possible for hackers to spoof these webhooks and make it appear to come from RaiseDonors, but in reality, it's coming from a hacker. The hacker will not know the security token - and this is why you need to verify the security token configured in the subscription is the same security token being received. A better approach is to leverage the RaiseDonors API and make a call back to RaiseDonors, using the unique webhook ID number - and retrieve the payload. This ensures no tampering has occurred. More information on the API for webhooks can be found here .
Static Objects
Some objects are enumerators meaning their value will be an integer rather than a text value. For example, the status of a donation will show "1" for Approved. A full list of these static objects is available in our API reference .
Full JSON Examples of Payloads
The XML equivalent will contain the same data elements.
Gift Added
{ "Event": "Gift Added", "EventDateTimeUtc": "2023-04-15T12:00:00Z", "Id": 12345, "IsTestMode": false, "Currency": "USD", "Amount": 100.00, "Date": "2023-04-15", "CreatedDate": "2023-04-15T12:00:00Z", "ModifiedDate": "2023-04-15T12:00:00Z", "Status": 1, "StatusText": "Approved", "Gateway": "Stripe", "TransactionId": "txn_123456789", "PaymentInfo": "Visa 4242", "PaymentType": "Credit Card", "Segment": "Annual Campaign", "Motivation": "Supporting the cause", "Notes": "First donation from this donor.", "Comment": "Keep up the great work!", "GoogleUtmCampaign": "Spring Fundraiser", "GoogleUtmSource": "Email", "GoogleUtmMedium": "Newsletter", "GoogleUtmContent": "Donate Button", "GoogleUtmTerm": "Fundraising", "DonorId": 67890, "BillingName": "John Doe", "ShippingName": "John Doe", "Page": { "Id": 34567, "Name": "Fundraising Event", "Slug": "fundraising-event", "PublicId": "abcdefg-12345", "Type": "Donation" }, "RecurringGift": null, "Premium": { "Event": "", "EventDateTimeUtc": "2023-04-01T00:00:00Z", "Id": 12345, "Name": "Annual Membership", "NameShort": "Membership", "Code": "ANNUAL2023", "Description": "Gain an annual membership with exclusive benefits.", "Price": 100.00, "IsActive": true, "IsFree": false, "FairMarketValue": 50.00, "DigitalUrl": "https://example.com/membership", "Inventory": 1000, "KeepActiveWhenHasNoInventory": false, "RecurringPremiumId": null, "RecurringPremiumName": null, "OtherMinimumAmounts": [ { "Currency": "USD", "Value": 100.00 }, { "Currency": "EUR", "Value": 90.00 } ] }, "Tribute": null, "BillingAddress": { "Id": 78901, "AddressType": "Home", "Address1": "123 Main St", "City": "Anytown", "State": "Anystate", "PostalCode": "12345", "Country": "USA" }, "ShippingAddress": { "Id": 78901, "AddressType": "Home", "Address1": "123 Main St", "City": "Anytown", "State": "Anystate", "PostalCode": "12345", "Country": "USA" }, "Projects": [ { "ProjectId": 1234 "Amount": 100.00 } ] }
Gift Modified
{ "Event": "Gift Modified", "EventDateTimeUtc": "2023-04-16T12:00:00Z", "Id": 12345, "IsTestMode": false, "Currency": "USD", "Amount": 150.00, "Date": "2023-04-15", "CreatedDate": "2023-04-15T12:00:00Z", "ModifiedDate": "2023-04-16T12:00:00Z", "Status": 4, "StatusText": "Refunded", "Gateway": "Stripe", "TransactionId": "txn_987654321", "PaymentInfo": "Visa ending in 4242", "PaymentType": "Credit Card", "Segment": "Annual Campaign", "Motivation": "Supporting the cause", "Notes": "Refund issued due to an overcharge.", "Comment": "", "GoogleUtmCampaign": "Spring Fundraiser", "GoogleUtmSource": "Email", "GoogleUtmMedium": "Newsletter", "GoogleUtmContent": "Donate Button", "GoogleUtmTerm": "Fundraising", "DonorId": 67890, "BillingName": "John Doe", "ShippingName": "John Doe", "Page": { "Id": 34567, "Name": "Fundraising Event", "Slug": "fundraising-event", "PublicId": "abcdefg-12345", "Type": "Donation" }, "RecurringGift": { "Event": "", "EventDateTimeUtc": "2023-04-01T00:00:00Z", "Id": 12345, "IsTestMode": false, "ProfileNumber": "abcdefg-12345", "StartDate": "2023-04-01", "NextChargeDate": "2024-05-01", "Frequency": 12, "FrequencyText": "Monthly", "Amount": 150.00, "DonorId": 67890, "Status": 1, "StatusText": "Active", "SuccessfulCycles": 0, "Total": 50.00, "PaymentTenderType": 1, "IsAnonymous": false, "Segment": "Online Donation", "Premium": { "Id": 987, "Name": "Gift Premium", "NameShort": "Gift", "Code": "GFT", "Description": "A special gift for recurring donors.", "FairMarketValue": 10.00, "Price": 0.00, "IsActive": true, "IsFree": true, "Inventory": 100, "KeepActiveWhenHasNoInventory": false }, "BillingAddress": { "Id": 123, "AddressType": 1, "Address1": "123 Main St", "Address2": "Suite 100", "City": "Anytown", "State": "Anystate", "PostalCode": "12345", "Country": "USA" }, "ShippingAddress": null, "Projects": [ { "ProjectId": 1234 "Amount": 50.00 } ] }, "Premium": null, "Tribute": { "Id": 123456, "TributeType": "In Memory Of", "NameOrOccasion": "John Doe Memorial", "TributeFirstName": "John", "TributeLastName": "Doe", "TributeAddress1": "123 Memory Lane", "TributeAddress2": "Suite 100", "TributeCity": "Memorial City", "TributeState": "Grief", "TributeCountry": "Heartland", "TributePostal": "12345", "AcknowledgeeFirstName": "Jane", "AcknowledgeeLastName": "Doe", "AcknowledgementMethod": "Email", "AcknowledgeeEmailAddress": "jane.doe@example.com", "AcknowledgeeAddress1": "321 Consolation Ave", "AcknowledgeeAddress2": "Apt 202", "AcknowledgeeCity": "Solace Town", "AcknowledgeeState": "Recovery", "AcknowledgeeCountry": "Heartland", "AcknowledgeePostal": "54321", "Message": "In loving memory of John Doe, a tribute has been made in his honor." }, "BillingAddress": { "Id": 78901, "AddressType": "Home", "Address1": "123 Main St", "City": "Anytown", "State": "Anystate", "PostalCode": "12345", "Country": "USA" }, "ShippingAddress": null, "Projects": [ { "ProjectId": 1234 "Amount": 50.00 } ] }
Donor Added
{ "Id": 123456, "IsTestMode": false, "FirstName": "John", "LastName": "Doe", "Name": "John Doe", "IsOrganization": false, "Notes": "New donor added to the system.", "Address": [ { "Id": 789, "AddressType": 1, "Address1": "123 Main St", "Address2": "Apt 4", "City": "Anytown", "State": "Anystate", "PostalCode": "12345", "Country": "USA" } ], "ContactMethods": [ { "Id": 456, "Type": 10, "Value": "john.doe@example.com", "SecondaryValue": null, "IsPrimary": true, "IsOptedIn": true, "IsValid": true, "IsEmail": true, "IsPhone": false }, { "Id": 457, "Type": 20, "Value": "555-1234", "SecondaryValue": null, "IsPrimary": true, "IsOptedIn": true, "IsValid": true, "IsEmail": false, "IsPhone": true } ] }
Donor Edited
{ "Id": 123456, "IsTestMode": false, "FirstName": "Johnathan", "LastName": "Doe", "Name": "Johnathan Doe", "IsOrganization": false, "Notes": "Donor information updated.", "Address": [ { "Id": 789, "AddressType": 1, "Address1": "456 Main St", "Address2": "Suite 100", "City": "Newtown", "State": "Newstate", "PostalCode": "67890", "Country": "USA" } ], "ContactMethods": [ { "Id": 456, "Type": 10, "Value": "johnathan.doe@example.com", "SecondaryValue": null, "IsPrimary": true, "IsOptedIn": true, "IsValid": true, "IsEmail": true, "IsPhone": false }, { "Id": 457, "Type": 20, "Value": "555-6789", "SecondaryValue": null, "IsPrimary": true, "IsOptedIn": true, "IsValid": true, "IsEmail": false, "IsPhone": true } ] }
Donor Deleted
{ "Id": 1001 "Event": “Donor Deleted”, "EventDateTimeUtc": "2023-04-12T15:30:00Z", }
Schedule Added
{ "Event": "Schedule Added", "EventDateTimeUtc": "2023-04-01T00:00:00Z", "Id": 12345, "IsTestMode": false, "ProfileNumber": "PRF1234567", "StartDate": "2023-04-01", "NextChargeDate": "2023-05-01", "Frequency": 1, "FrequencyText": "Monthly", "Amount": 50.00, "DonorId": 67890, "Status": 1, "StatusText": "Active", "SuccessfulCycles": 0, "Total": 50.00, "PaymentTenderType": 1, "IsAnonymous": false, "Segment": "Online Donation", "Premium": { "Id": 987, "Name": "Gift Premium", "NameShort": "Gift", "Code": "GFT", "Description": "A special gift for recurring donors.", "FairMarketValue": 10.00, "Price": 0.00, "IsActive": true, "IsFree": true, "Inventory": 100, "KeepActiveWhenHasNoInventory": false }, "BillingAddress": { "Id": 123, "AddressType": 1, "Address1": "123 Main St", "Address2": "Suite 100", "City": "Anytown", "State": "Anystate", "PostalCode": "12345", "Country": "USA" }, "ShippingAddress": null, "Projects": [ { "ProjectId": 1234 "Amount": 50.00 } ] }
Schedule Modified
{ "Event": "Schedule Modified", "EventDateTimeUtc": "2023-04-15T00:00:00Z", "Id": 12345, "IsTestMode": false, "ProfileNumber": "PRF1234567", "StartDate": "2023-04-01", "NextChargeDate": "2023-06-01", "Frequency": 1, "FrequencyText": "Monthly", "Amount": 75.00, "DonorId": 67890, "Status": 1, "StatusText": "Active", "SuccessfulCycles": 1, "Total": 125.00, "PaymentTenderType": 1, "IsAnonymous": false, "Segment": "Online Donation", "Premium": { "Id": 987, "Name": "Gift Premium", "NameShort": "Gift", "Code": "GFT", "Description": "A special gift for recurring donors.", "FairMarketValue": 10.00, "Price": 0.00, "IsActive": true, "IsFree": true, "Inventory": 99, "KeepActiveWhenHasNoInventory": false }, "BillingAddress": { "Id": 123, "AddressType": 1, "Address1": "123 Main St", "Address2": "Suite 100", "City": "Anytown", "State": "Anystate", "PostalCode": "12345", "Country": "USA" }, "ShippingAddress": null, "Projects": [] }
Schedule Deleted
{ "Id": 2222 "Event": “Schedule Deleted”, "EventDateTimeUtc": "2023-04-12T15:30:00Z", }
Project Added
{ "eventType": "Project Added", "eventDateTimeUtc": "2023-04-01T00:00:00Z", "Id": 101, "Code": "PRJ2023", "IsActive": true, "IsDeleted": false, "Name": "Clean Water Initiative", "Description": "A project aimed at providing clean drinking water to underserved communities.", "CreatedDateTime": "2023-04-01T00:00:00Z", "ModifiedDateTime": "2023-04-01T00:00:00Z", "DonorAmount": 0, "GiftAmount": 0, "RaisedAmount": 0, "AverageGiftAmount": 0, "FirstGiftDate": null, "LastGiftDate": null }
Project Modified
{ "eventType": "Project Modified", "eventDateTimeUtc": "2023-04-15T00:00:00Z", "Id": 101, "Code": "PRJ2023", "IsActive": true, "IsDeleted": false, "Name": "Clean Water Initiative - Phase 2", "Description": "The second phase of the project, expanding clean water access to additional communities.", "CreatedDateTime": "2023-04-01T00:00:00Z", "ModifiedDateTime": "2023-04-15T00:00:00Z", "DonorAmount": 100, "GiftAmount": 50, "RaisedAmount": 5000, "AverageGiftAmount": 100, "FirstGiftDate": "2023-04-02T00:00:00Z", "LastGiftDate": "2023-04-14T00:00:00Z" }
Project Deleted
{ "Id": 1231 "Event": “Project Deleted”, "EventDateTimeUtc": "2023-04-12T15:30:00Z", }
Premium Added
{ "Event": "Premium Added", "EventDateTimeUtc": "2023-04-01T00:00:00Z", "Id": 12345, "Name": "Annual Membership", "NameShort": "Membership", "Code": "ANNUAL2023", "Description": "Gain an annual membership with exclusive benefits.", "Price": 100.00, "IsActive": true, "IsFree": false, "FairMarketValue": 50.00, "DigitalUrl": "https://example.com/membership", "Inventory": 1000, "KeepActiveWhenHasNoInventory": false, "RecurringPremiumId": null, "RecurringPremiumName": null, "OtherMinimumAmounts": [ { "Currency": "USD", "Value": 100.00 }, { "Currency": "EUR", "Value": 90.00 } ] }
Premium Modified
{ "Event": "Premium Modified", "EventDateTimeUtc": "2023-04-15T00:00:00Z", "Id": 12345, "Name": "Annual Membership Plus", "NameShort": "Membership+", "Code": "ANNUALPLUS2023", "Description": "Enhanced annual membership with additional exclusive benefits.", "Price": 150.00, "IsActive": true, "IsFree": false, "FairMarketValue": 75.00, "DigitalUrl": "https://example.com/membership-plus", "Inventory": 950, "KeepActiveWhenHasNoInventory": true, "RecurringPremiumId": null, "RecurringPremiumName": null, "OtherMinimumAmounts": [ { "Currency": "USD", "Value": 150.00 }, { "Currency": "EUR", "Value": 135.00 } ] }
Premium Deleted
{ "Id": 222 "Event": “Premium Deleted”, "EventDateTimeUtc": "2023-04-12T15:30:00Z", }
Comments
0 comments
Article is closed for comments.