We are excited to announce the launching of the Custom Webhooks feature!
Donorbox supported webhooks through Zapier integrations which helps you to connect your Donorbox account with various third-party applications. This feature has now been enhanced which allows you to register custom endpoint URLs.
With custom webhooks, you can now enable your applications to be notified instantly and execute actions accordingly whenever an event occurs in your Donorbox account.
Following events which are currently available for Zapier integrations are also made available for custom endpoint URLs.
- New/Update donation
Whenever a new donation is received or an existing donation is updated, this event is triggered. A post request is submitted to the specified endpoint URL with a JSON payload. The payload is an array containing one JSON object with the details of the donation record. Below is the sample payload that is submitted when this event is triggered:
[ {
"action": "new", "campaign": { "id": 1, "name": "Donorbox Campaign" }, "donor": { "id": 59, "name": "John Doe", "first_name": "John", "last_name": "Doe", "email": "johndoeemail@hotmail.com", "address":"123 6th St.",
"address_line_2":"Lakeside Road", "city":"Melbourne", "state":"FL", "zip_code": "32904", "country":"US", "employer":null, "occupation":null }, "amount": "100.0", "formatted_amount": "$100", "converted_amount": "100.0", "formatted_converted_amount": "$100", "recurring": false, "first_recurring_donation": false, "amount_refunded": "0.0", "formatted_amount_refunded": "$0", "stripe_charge_id": "ch_1BF94aBku99FiTp3uJM5mSKw", "id": 1, "status": "paid", "donation_type": "stripe", "donation_date": "2017-12-21T17:54:13.432Z", "anonymous_donation": false, "gift_aid": false, "designation": "Designed Cause", "join_mailing_list": false, "comment": "thanks", "donating_company": null, "currency": "USD", "converted_currency": "USD", "utm_campaign": "google_ads", "utm_source": "Adwords", "utm_medium": "cpc", "utm_term": "nonprofit fundraising", "utm_content": "np1", "processing_fee": 0.59, "formatted_processing_fee": "$0.59",
"address": "123 6th St.",
"address_line_2": "Lakeside Road",
"city": "Melbourne",
"state": "FL",
"zip_code": "32904",
"country": "US",
"employer": null,
"occupation": null, "questions": [ { "question_type": "radiobutton", "question": "Would you like to volunteer?", "answer": "Yes" }, { "question_type": "text", "question": "Why are you donating", "answer": "I would like to help" }, { "question_type": "check", "question": "First/Last Name is correct?", "answer": true }, { "question_type": "dropdown", "question": "Would you like to showcase your donation", "answer": "Yes" } ] } ] - New/Update donor
Whenever a new donor is created or an existing donor is updated, this event is triggered. A post request is submitted to the specified endpoint URL with a JSON payload. The payload is an array containing one JSON object with the details of the donor record. Below is the sample payload that is submitted when this event is triggered:
[ {
"action": "update", "id":35, "created_at":"2017-11-20T14:01:35.597Z", "updated_at":"2017-11-28T21:49:25.127Z", "first_name":"John", "last_name":"Doe", "email":"johndoe@email.com", "phone":"123456789", "address":"123 6th St.", "city":"Melbourne", "state":"FL", "zip_code":"32904", "country":"USA", "employer":null, "occupation":null, "comment":null, "donations_count":2, "last_donation_at":"2017-11-28T21:48:51.260Z", "total":[ { "currency":"usd", "value":100.0 } ] } ] - New/Update campaign
Whenever a new campaign is created or an existing campaign is updated, this event is triggered. A post request is submitted to the specified endpoint URL with a JSON payload. The payload is an array containing one JSON object with the details of the campaign record. Below is the sample payload that is submitted when this event is triggered:
[ {
"action": "new", "id":1, "name":"Donorbox New Campaign", "slug":"donorbox-new-campaign", "currency":"usd", "created_at":"2017-10-20T22:30:55.620Z", "updated_at":"2017-10-20T22:30:55.620Z", "goal_amt":"10000.0", "formatted_goal_amount":"$1,0000", "total_raised":"2000.0", "formatted_total_raised":"$2000", "donations_count":66 } ] - New/Update plan
Whenever a new recurring plan is created or an existing plan is updated, this event is triggered. A post request is submitted to the specified endpoint URL with a JSON payload. The payload is an array containing one JSON object with the details of the recurring plan. Below is the sample payload that is submitted when this event is triggered:
[ {
"action": "new", "id": 168, "campaign": { "id": 61, "name": "Save the jungle campaign" }, "donor": { "id": 384, "name": "Bruce Waine", "first_name": "Bruce", "last_name": "Waine", "email": "bruce@email.com", "phone": "8038984624", "address": "123 6th St.", "city":"Melbourne", "state":"FL", "zip_code":"32904", "country": "USA", "employer": "Waine Industries", "occupation": "CEO" }, "type": "monthly", "amount": "10.0", "formatted_amount": "$10", "payment_method": "Stripe", "started_at": "2018-07-25", "last_donation_date": "2018-07-25T05:00:00.000Z", "next_donation_date": "2018-08-25", "status": "active" } ]
How to add a custom webhook endpoint URL?
To make use of the custom webhooks feature, you need to enable the add-on "API & Zapier integration" or upgrade to the "Premium" plan
To enable the add-on:
Login to your Donorbox account, click Add-ons in the left sidebar > click API & Zapier Integration, and click Activate Zapier Integration.
To upgrade to the premium plan:
Login to your Donorbox account, click on the "Upgrade" button on the bottom of the left sidebar
1. Once you have the add-on enabled, you can add the custom webhook URL on the "API & Zapier Integration" page. When there are no custom webhook URLs added yet, you will see the option to add one, like in the below screenshot.
2. Clicking on the button will display the "Add Custom Webhook" form
3. Enter the endpoint URL and choose the event type that should trigger a notification to the endpoint URL, then click "Add Endpoint" to submit the form.
4. Once the form is successfully submitted, you will see the endpoint URL successfully added.
5. You can add more endpoint URLs by clicking on the "Add new endpoint URL" button.
6. You can enable/disable notifications to the endpoint URL by toggling the switch shown in the above screenshot.
How to verify that the webhook received at your endpoint URL was triggered by Donorbox?
Since your endpoint URLs are public, it is easily accessible to any third party on the internet. That means anyone with malicious intentions can flood your endpoint URL with bad requests pretending it to be from Donorbox. To overcome such bad actors, Donorbox sends a signed signature for each webhook notification request. More details about how to validate the webhook requests from Donorbox can be found in this guide https://donorbox.zendesk.com/hc/en-us/articles/17982194843028.
Webhook notification delays
Webhook notifications are typically anticipated to be dispatched promptly within a few seconds of the triggering event, barring peak periods when our daily recurring scheduler is activated. During this interval, there may be a noticeable augmentation in the size of the webhook queue, resulting in a delay of up to approximately one hour.
If you have any queries/suggestions, please reach out to our support team at support@donorbox.org.
Comments
0 comments
Article is closed for comments.