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 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.
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.
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 .
Project- the most recently created project.
Campaign - the most recently edited campaign.
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 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.found here .
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 .
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.
JSON examples of payloads
The XML equivalent will contain the same data elements.
Donation.Created
{
"Donation": {
"Id": 436,
"Amount": 4,
"AuthorizationNumber": "ch_1D6pW7DdkMNzTS0Mi4UGnQs1",
"Last4ofTenderType": "0005",
"MotivationCode": "",
"SourceCode": "",
"Status": 1,
"CardBrand": 1,
Donation.Edited
{
"Donation": {
"Id": 7,
"Amount": 50,
"AuthorizationNumber": "test",
"Last4ofTenderType": "0012",
"MotivationCode": "test-motivation",
"SourceCode": "test-source",
"Status": 1,
"CardBrand": 4,
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,
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,
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,
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"
}
Project.Created
{
"Project": {
"Id": 1,
"Name": "Default",
"Code": "DEF",
"Description": "Default project for donations."
},
"Id": 89,
"EventType": "Project.Created",
"DateCreated": "2018-09-05T16:12:27.2709382+00:00",
"Key": "lasdjfalsflasdfjasdjklfalsjdfasf"
}
Project.Edited
{
"Project": {
"Id": 1,
"Name": "Default",
"Code": "DEF",
"Description": "Default project for donations."
},
"Id": 90,
"EventType": "Project.Edited",
"DateCreated": "2018-09-05T16:12:36.5844202+00:00",
"Key": "lasdjfalsflasdfjasdjklfalsjdfasf"
}
Project.Deleted
{
"Project": {
"Id": 1,
"Name": "Default",
"Code": "DEF",
"Description": "Default project for donations."
},
"Id": 91,
"EventType": "project.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,
Campaign.Edited
{
"Campaign": {
"Id": 1,
"Title": "Your first donation page",
"Url": "donation-page",
"NumVisitorsToPage": 0,
Campaign.Deleted
{
"Campaign": {
"Id": 1,
"Title": "Your first donation page",
"Url": "donation-page",
"NumVisitorsToPage": 0,
