Use webhooks to be notified about events that happen in your RaiseDonors account. RaiseDonors can send webhook events that notify your application any time an 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 may include...
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.
Webhooks are configured in the Admin dashboard Webhooks settings section. Click Add subscription to reveal a form where you can add a new subscription for receiving webhooks.
RaiseDonors supports many webhook types. The naming convention follows the principle of {object}.{verb}.
You can enter any URL as the destination for events. However, this should be a dedicated page on your server that is set up to receive webhook notifications. You can choose to be notified of all event types, or only specific ones.
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 retry
1 minute delay
Second retry
30 minute delay
Third retry
1 hour delay
Fourth retry
2 hour delay
Fifth retry
4 hour delay
Sixth retry
8 hour delay
Seventh retry
1 day delay
Eighth retry
1 day delay
Ninth retry
1 day delay
Tenth retry
Cancelled
Webhooks cannot be manually retried after this time, though you can query for the event to reconcile your data with any missed events.
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.
Before going live, test that your webhook is working properly. You can do so by sending dummy test events from the Webhooks settings pane. To do this, log into RaiseDonors and head over to the webhook subscriptions page. From there, you can click the 'test' button for each subscription. RaiseDonors will look for data as follows,
Donation - the most recently modified donation that has been created in test mode .
Donor - the most recently modified donor who has at least one donation in test mode .
Recurring Schedule - the most recently modified schedule which has at least one donation in test mode .
Fund - the most recently created fund.
Campaign - the most recently edited campaign.
If you need help sending any of the above events in test mode, check this resource .
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. For that reason, you might want to have your webhook endpoint immediately acknowledge receipt by returning a 2xx
HTTP status code, and then perform the rest of its duties.
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 miliseconds of the actual event taking place; as close to real-time as possible. However the webhook system is dependent up 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.
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 .
Example payloads
The best way to preview what the webhook payloads include is to leverage a listening service or make GET requests to the API endpoint "Webhook Subscription (Empty) ". We've seen great simplicity and results with https://webhook.site/
This is a website designed to listen for incoming requests. So go build a webhook subscription in RaiseDonors - and point that subscription to the unique url at webhook.site that was generated for you. Then click the "test" button on the webhook subscription - and you will immediately see a list of the incoming webhooks. This will always provide the most accurate and up to date payloads RaiseDonors sends with webhook event notifications.
For reference purposes only, we have also included JSON examples of payloads below. The XML equivalent will contain the same data elements.
{
"Donation": {
"Id": 436,
"Amount": 4,
"AuthorizationNumber": "ch_1D6pW7DdkMNzTS0Mi4UGnQs1",
"Last4ofTenderType": "0005",
"MotivationCode": "",
"SourceCode": "",
"Status": 1,
"CardBrand": 1, "GiftAidRequested": true,
"PaymentTenderType": 1,
"GatewayTransDetails": "ch_1D6pW7DdkMNzTS0Mi4UGnQs1",
"TransactionId": "ch_1D6pW7DdkMNzTS0Mi4UGnQs1",
"TestMode": true,
"DonorCoversProcessingFee": false,
"DonorCoversProcessingFee_Percentage": "",
"DonorCoversProcessingFee_AmtForFee": "",
"DonorCoversProcessingFee_AmtForDonation": "",
"VirtualTerminal_Used": false,
"VirtualTerminal_PlacedBy": "",
"ReferralUrl": "",
"RawUrl": "",
"GoogleUtmTerm": "",
"GoogleUtmCampaign": "",
"GoogleUtmContent": "",
"GoogleUtmMedium": "",
"GoogleUtmSource": "",
"RefundedAmount": 0,
"Comment": "",
"CCExpiry": "6/2019",
"DateCreated": "2018-09-05T01:09:22.913",
"LastModified": "2018-09-05T01:09:24.803",
"LastModifiedBy": "Catherin Cushman",
"LastIPAddress": "stripe Web Hook Notification",
"MediaOutlet": null,
"Gateway": {
"Id": 17,
"Name": "official stripe acct (RDStaging Acct)",
"VendorName": "stripe"
},
"Page": {
"Id": 5,
"Title": "imported-donors",
"Url": "imported-donors",
"NumVisitorsToPage": 0,
"MotivationCode": "",
"SourceCode": "",
"DateCreated": "2018-06-18T06:30:30.007",
"LastModified": "2018-06-18T06:30:30.007",
"LastModifiedBy": "stripe Web Hook Notification",
"ProductCode": "",
"RecurringProductCode": null,
"FairMarketValue": 0,
"ProductCodeName": null,
"PublicTitle": "imported-donors"
},
"Donor": {
"Id": 167,
"FName": "Ray",
"LName": "Tester4",
"Email": "stripe-4th-recurring@melmex.com",
"Phone": "",
"DateCreated": "2018-09-05T01:09:23.647",
"LastModified": "2018-09-05T01:09:24.117",
"LastLogin": null,
"LastModifiedBy": "Ray Tester4",
"LastIPAccess": "N/A",
"NesletterOptIn": false,
"IsLockedOut": false,
"BadPasswordCount": 0,
"LifetimeLoginCount": 0,
"CRMKey": null,
"CRMSecondKey": null,
"OrganizationName": "",
"IsEmailSendingSuppressed": false,
"EmailSendingSuppresionReason": null, "IsFirstTimeDonor": true,
"DonorAddresses": [
{
"Id": 167,
"Address1": "544 N Denton Tap Rd",
"City": "Coppell",
"State": "Texas",
"Zip": "75019",
"Country": "USA",
"DateCreated": "2018-09-05T01:09:23.617",
"LastModified": "2018-09-05T01:09:24.117",
"LastModifiedBy": "Ray Tester4",
"LastIPAddress": "N/A",
"AddressType": 2,
"FName": "Ray",
"LName": "Tester4"
}
]
},
"RecurringSchedule": {
"Id": 187,
"StartDate": "2018-09-05T00:00:00",
"Frequency": 12,
"ScheduleNumber": "sub_AUfPff3g9RObWX",
"Status": 1,
"Amount": 4,
"NextChargeDate": "2018-10-05T00:00:00",
"DonorId": 167,
"GatewayCustomerKey": "",
"PaymentTenderType": 1,
"AchAcctType": "",
"isDeleted": false,
"DateCreated": "2018-09-05T01:09:23.867",
"LastModified": "2018-09-05T01:09:24.023",
"Gateway": {
"Id": 17,
"Name": "official stripe acct (RDStaging Acct)",
"VendorName": "stripe"
}
},
"DonationAddresses": [
{
"Id": 432,
"Address1": "544 N Denton Tap Rd",
"City": "Coppell",
"State": "Texas",
"Zip": "75019",
"Country": "USA",
"DateCreated": "2018-09-05T01:09:23.617",
"LastModified": "2018-09-05T01:09:23.617",
"LastModifiedBy": "Ray Tester4",
"LastIPAddress": "N/A",
"AddressType": 2,
"FName": "Ray",
"LName": "Tester4"
}
],
"FundAllocations": [
{
"Id": 434,
"Amount": 4,
"IsRefunded": false,
"Fund": {
"Id": 4,
"Name": "test",
"Code": "asrwadsf",
"Description": "asdfad"
}
}
],
"InHonorMemoryOf": null
},
"Id": 1447,
"EventType": "Donation.Created",
"DateCreated": "2018-09-05T01:09:24.845934+00:00",
"Key": "23423423423234234"
}
Donation.Edited
{
"Donation": {
"Id": 7,
"Amount": 50,
"AuthorizationNumber": "test",
"Last4ofTenderType": "0012",
"MotivationCode": "test-motivation",
"SourceCode": "test-source",
"Status": 1,
"CardBrand": 4, "GiftAidRequested": true,
"PaymentTenderType": 1,
"GatewayTransDetails": "Success, Test Mode",
"TransactionId": "test",
"TestMode": true,
"DonorCoversProcessingFee": false,
"DonorCoversProcessingFee_Percentage": "",
"DonorCoversProcessingFee_AmtForFee": "",
"DonorCoversProcessingFee_AmtForDonation": "",
"VirtualTerminal_Used": false,
"VirtualTerminal_PlacedBy": "",
"ReferralUrl": "N/A",
"RawUrl": "http://localhost:59622/donate.aspx?org",
"GoogleUtmTerm": "",
"GoogleUtmCampaign": "",
"GoogleUtmContent": "",
"GoogleUtmMedium": "",
"GoogleUtmSource": "",
"RefundedAmount": 0,
"Comment": "",
"CCExpiry": "10/2020",
"DateCreated": "2018-08-16T22:58:54.89",
"LastModified": "2018-08-17T02:21:10.043",
"LastIPAddress": "127.0.0.1",
"MediaOutlet": null,
"Gateway": {
"Id": 1,
"Name": "-|*RaiseDonors*Test*Gateway*|-",
"VendorName": "auth_net"
},
"Page": {
"Id": 1,
"Title": "Your first donation page",
"Url": "donation-page",
"NumVisitorsToPage": 0,
"MotivationCode": "test-motivation",
"SourceCode": "test-source",
"DateCreated": "2018-08-15T23:58:01.977",
"LastModified": "2018-08-16T00:14:51.89",
"LastModifiedBy": "chris mechsner",
"ProductCode": "",
"RecurringProductCode": "",
"FairMarketValue": 0,
"ProductCodeName": null,
"PublicTitle": "Donation Page"
},
"Donor": {
"Id": 6,
"FName": "Ant",
"LName": "Aguillon22",
"Email": "raisedonorstest+Ant+webhooks@gmail.com",
"Phone": "123-123-1234",
"DateCreated": "2018-08-16T22:58:30.71",
"LastModified": "2018-08-26T16:10:02.183",
"LastLogin": null,
"LastModifiedBy": "Ant Aguillon22",
"LastIPAccess": "127.0.0.1",
"NesletterOptIn": false,
"IsLockedOut": false,
"BadPasswordCount": 0,
"LifetimeLoginCount": 3,
"CRMKey": "",
"CRMSecondKey": "441251",
"OrganizationName": "",
"IsEmailSendingSuppressed": false,
"EmailSendingSuppresionReason": null, "IsFirstTimeDonor": true,
"DonorAddresses": [
{
"Id": 6,
"Address1": "65 N Denton Tap Rd",
"City": "Coppell",
"State": "TX",
"Zip": "75019",
"Country": "US",
"DateCreated": "2018-08-16T22:58:30.707",
"LastModified": "2018-08-16T22:58:30.707",
"LastModifiedBy": "Antonina Aguillon",
"LastIPAddress": "127.0.0.1",
"AddressType": 2,
"FName": "Ant",
"LName": "Aguillon22"
}
]
},
"RecurringSchedule": null,
"DonationAddresses": [
{
"Id": 7,
"Address1": "65 N Denton Tap Rd",
"City": "Coppell",
"State": "Texas",
"Zip": "75019",
"Country": "USA",
"DateCreated": "2018-08-16T22:58:54.897",
"LastModified": "2018-08-16T22:58:54.897",
"LastModifiedBy": "Antonina Aguillon",
"LastIPAddress": "127.0.0.1",
"AddressType": 2,
"FName": "Antonina",
"LName": "Aguillon"
}
],
"FundAllocations": [
{
"Id": 7,
"Amount": 50,
"IsRefunded": false,
"Fund": {
"Id": 1,
"Name": "Default",
"Code": "DEF",
"Description": "Default fund for donations."
}
}
],
"InHonorMemoryOf": null
},
"Id": 85,
"EventType": "Donation.Edited",
"DateCreated": "2018-09-05T16:12:23.6451641+00:00",
"Key": "lasdjfalsflasdfjasdjklfalsjdfasf"
}
Donor.Created
{
"Donor": {
"Id": 167,
"FName": "Ray",
"LName": "Tester4",
"Email": "stripe-4th-recurring@melmex.com",
"Phone": "",
"DateCreated": "2018-09-05T01:09:23.647",
"LastModified": "2018-09-05T01:09:24.117",
"LastLogin": null,
"LastModifiedBy": "Ray Tester4",
"LastIPAccess": "N/A",
"NesletterOptIn": false,
"IsLockedOut": false,
"BadPasswordCount": 0,
"LifetimeLoginCount": 0,
"CRMKey": null,
"CRMSecondKey": null,
"OrganizationName": "",
"IsEmailSendingSuppressed": false,
"EmailSendingSuppresionReason": null, "IsFirstTimeDonor": true,
"DonorAddresses": [
{
"Id": 167,
"Address1": "544 N Denton Tap Rd",
"City": "Coppell",
"State": "Texas",
"Zip": "75019",
"Country": "USA",
"DateCreated": "2018-09-05T01:09:23.617",
"LastModified": "2018-09-05T01:09:24.117",
"LastModifiedBy": "Ray Tester4",
"LastIPAddress": "N/A",
"AddressType": 2,
"FName": "Ray",
"LName": "Tester4"
}
]
},
"Id": 1441,
"EventType": "Donor.Created",
"DateCreated": "2018-09-05T01:09:24.2533841+00:00",
"Key": "23423423423234234"
}
Donor.Edited
{
"Donor": {
"Id": 167,
"FName": "Ray",
"LName": "Tester4",
"Email": "stripe-4th-recurring@melmex.com",
"Phone": "",
"DateCreated": "2018-09-05T01:09:23.647",
"LastModified": "2018-09-05T01:09:24.117",
"LastLogin": null,
"LastModifiedBy": "Ray Tester4",
"LastIPAccess": "N/A",
"NesletterOptIn": false,
"IsLockedOut": false,
"BadPasswordCount": 0,
"LifetimeLoginCount": 0,
"CRMKey": null,
"CRMSecondKey": null,
"OrganizationName": "",
"IsEmailSendingSuppressed": false,
"EmailSendingSuppresionReason": null, "IsFirstTimeDonor": true,
"DonorAddresses": [
{
"Id": 167,
"Address1": "544 N Denton Tap Rd",
"City": "Coppell",
"State": "Texas",
"Zip": "75019",
"Country": "USA",
"DateCreated": "2018-09-05T01:09:23.617",
"LastModified": "2018-09-05T01:09:24.117",
"LastModifiedBy": "Ray Tester4",
"LastIPAddress": "N/A",
"AddressType": 2,
"FName": "Ray",
"LName": "Tester4"
}
]
},
"Id": 1448,
"EventType": "Donor.Edited",
"DateCreated": "2018-09-05T01:09:24.8518931+00:00",
"Key": "23423423423234234"
}
Donor.Deleted
{
"Donor": {
"Id": 6,
"FName": "Ant",
"LName": "Aguillon22",
"Email": "raisedonorstest+Ant+webhooks@gmail.com",
"Phone": "123-123-1234",
"DateCreated": "2018-08-16T22:58:30.71",
"LastModified": "2018-08-26T16:10:02.183",
"LastLogin": null,
"LastModifiedBy": "Ant Aguillon22",
"LastIPAccess": "127.0.0.1",
"NesletterOptIn": false,
"IsLockedOut": false,
"BadPasswordCount": 0,
"LifetimeLoginCount": 3,
"CRMKey": "",
"CRMSecondKey": "441251",
"OrganizationName": "",
"IsEmailSendingSuppressed": false,
"EmailSendingSuppresionReason": null, "IsFirstTimeDonor": true,
"DonorAddresses": [
{
"Id": 6,
"Address1": "65 N Denton Tap Rd",
"City": "Coppell",
"State": "TX",
"Zip": "75019",
"Country": "US",
"DateCreated": "2018-08-16T22:58:30.707",
"LastModified": "2018-08-16T22:58:30.707",
"LastModifiedBy": "Antonina Aguillon",
"LastIPAddress": "127.0.0.1",
"AddressType": 2,
"FName": "Ant",
"LName": "Aguillon22"
}
]
},
"Id": 88,
"EventType": "Donor.Deleted",
"DateCreated": "2018-09-05T16:12:26.0367855+00:00",
"Key": "lasdjfalsflasdfjasdjklfalsjdfasf"
}
Schedule.Created
{
"RecurringSchedule": {
"Id": 187,
"StartDate": "2018-09-05T00:00:00",
"Frequency": 12,
"ScheduleNumber": "sub_AUfPff3g9RObWX",
"Status": 1,
"Amount": 4,
"NextChargeDate": "2018-10-05T00:00:00",
"DonorId": 167,
"GatewayCustomerKey": "",
"PaymentTenderType": 1,
"AchAcctType": "",
"isDeleted": false,
"DateCreated": "2018-09-05T01:09:23.867",
"LastModified": "2018-09-05T01:09:24.023",
"Gateway": {
"Id": 17,
"Name": "official stripe acct (RDStaging Acct)",
"VendorName": "stripe"
}
},
"Id": 1445,
"EventType": "Schedule.Created",
"DateCreated": "2018-09-05T01:09:24.44705+00:00",
"Key": "23423423423234234"
}
Schedule.Edited
{
"RecurringSchedule": {
"Id": 187,
"StartDate": "2018-09-05T00:00:00",
"Frequency": 12,
"ScheduleNumber": "sub_AUfPff3g9RObWX",
"Status": 1,
"Amount": 4,
"NextChargeDate": "2018-10-05T00:00:00",
"DonorId": 167,
"GatewayCustomerKey": "cus_AUfPc9iScJIt1R",
"PaymentTenderType": 1,
"AchAcctType": "",
"isDeleted": false,
"DateCreated": "2018-09-05T01:09:23.867",
"LastModified": "2018-09-05T01:09:25.07",
"Gateway": {
"Id": 17,
"Name": "official stripe acct (RDStaging Acct)",
"VendorName": "stripe"
}
},
"Id": 1453,
"EventType": "Schedule.Edited",
"DateCreated": "2018-09-05T01:09:25.5427543+00:00",
"Key": "23423423423234234"
}
Schedule.Deleted
{
"RecurringSchedule": {
"Id": 187,
"StartDate": "2018-09-05T00:00:00",
"Frequency": 12,
"ScheduleNumber": "sub_AUfPff3g9RObWX",
"Status": 1,
"Amount": 4,
"NextChargeDate": "2018-10-05T00:00:00",
"DonorId": 167,
"GatewayCustomerKey": "cus_AUfPc9iScJIt1R",
"PaymentTenderType": 1,
"AchAcctType": "",
"isDeleted": false,
"DateCreated": "2018-09-05T01:09:23.867",
"LastModified": "2018-09-05T01:09:25.07",
"Gateway": {
"Id": 17,
"Name": "official stripe acct (RDStaging Acct)",
"VendorName": "stripe"
}
},
"Id": 1453,
"EventType": "Schedule.Deleted",
"DateCreated": "2018-09-05T01:09:25.5427543+00:00",
"Key": "23423423423234234"
}
Fund.Created
{
"Fund": {
"Id": 1,
"Name": "Default",
"Code": "DEF",
"Description": "Default fund for donations."
},
"Id": 89,
"EventType": "Fund.Created",
"DateCreated": "2018-09-05T16:12:27.2709382+00:00",
"Key": "lasdjfalsflasdfjasdjklfalsjdfasf"
}
Fund.Edited
{
"Fund": {
"Id": 1,
"Name": "Default",
"Code": "DEF",
"Description": "Default fund for donations."
},
"Id": 90,
"EventType": "Fund.Edited",
"DateCreated": "2018-09-05T16:12:36.5844202+00:00",
"Key": "lasdjfalsflasdfjasdjklfalsjdfasf"
}
Fund.Deleted
{
"Fund": {
"Id": 1,
"Name": "Default",
"Code": "DEF",
"Description": "Default fund for donations."
},
"Id": 91,
"EventType": "Fund.Deleted",
"DateCreated": "2018-09-05T16:12:36.9221596+00:00",
"Key": "lasdjfalsflasdfjasdjklfalsjdfasf"
}
Campaign.Created
{
"Campaign": {
"Id": 1,
"Title": "Your first donation page",
"Url": "donation-page",
"NumVisitorsToPage": 0, "GiftAidEnabled": true,
"MotivationCode": "test-motivation",
"SourceCode": "test-source",
"DateCreated": "2018-08-15T23:58:01.977",
"LastModified": "2018-08-16T00:14:51.89",
"LastModifiedBy": "chris mechsner",
"ProductCode": "",
"RecurringProductCode": "",
"FairMarketValue": 0,
"ProductCodeName": null,
"PublicTitle": "Donation Page"
},
"Id": 92,
"EventType": "Campaign.Created",
"DateCreated": "2018-09-05T16:12:37.8201892+00:00",
"Key": "lasdjfalsflasdfjasdjklfalsjdfasf"
}
Campaign.Edited
{
"Campaign": {
"Id": 1,
"Title": "Your first donation page",
"Url": "donation-page",
"NumVisitorsToPage": 0, "GiftAidEnabled": true,
"MotivationCode": "test-motivation",
"SourceCode": "test-source",
"DateCreated": "2018-08-15T23:58:01.977",
"LastModified": "2018-08-16T00:14:51.89",
"LastModifiedBy": "chris mechsner",
"ProductCode": "",
"RecurringProductCode": "",
"FairMarketValue": 0,
"ProductCodeName": null,
"PublicTitle": "Donation Page"
},
"Id": 93,
"EventType": "Campaign.Edited",
"DateCreated": "2018-09-05T16:12:37.8967993+00:00",
"Key": "lasdjfalsflasdfjasdjklfalsjdfasf"
}
Campaign.Deleted
{
"Campaign": {
"Id": 1,
"Title": "Your first donation page",
"Url": "donation-page",
"NumVisitorsToPage": 0, "GiftAidEnabled": true,
"MotivationCode": "test-motivation",
"SourceCode": "test-source",
"DateCreated": "2018-08-15T23:58:01.977",
"LastModified": "2018-08-16T00:14:51.89",
"LastModifiedBy": "chris mechsner",
"ProductCode": "",
"RecurringProductCode": "",
"FairMarketValue": 0,
"ProductCodeName": null,
"PublicTitle": "Donation Page"
},
"Id": 94,
"EventType": "Campaign.Deleted",
"DateCreated": "2018-09-05T16:12:38.2231038+00:00",
"Key": "lasdjfalsflasdfjasdjklfalsjdfasf"
}
Comments
0 comments
Please sign in to leave a comment.