You can use Webhooks to be notified about events that happen in your Virtuous Raise account. Virtuous Raise can send Webhook events that notify your application any time a specific event happens from within Virtuous Raise. 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.—Virtuous Raise 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. Virtuous Raise 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 Virtuous Raise send a single event to many Webhook endpoints.
Virtuous Raise supports many Webhook types. The naming convention follows the principle of {object} {verb}. To access Webhooks from your Virtuous Raise 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, Virtuous Raise 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.
Back to top of page
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 Virtuous Raise 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. Virtuous Raise will ignore any other information returned in the request headers or request body. Virtuous Raise 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.
Back to top of page
Best Practices
If your Webhook script performs complex logic, or makes network calls, it's possible that the script would time out before Virtuous Raise 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
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.
Back to top of page
Security
Virtuous Raise 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 Virtuous Raise. 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.More information on the API for Webhooks can be found here.
Back to top of page
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.
Back to top of page
Full JSON Examples of Payloads
The XML equivalent will contain the same data elements.
Gift Added
{
Gift Modified
{
Donor Added
{
Donor Edited
{
Donor Deleted
{
Schedule Added
{
Schedule Modified
{
Schedule Deleted
{
Project Added
{
Project Modified
{
Project Deleted
{
Premium Added
{
Premium Modified
{
Premium Deleted
{
