Skip to main content

How to get started using Virtuous Volunteer Webhooks?

Molly Kinder
  • Updated
Note: In a recent product update,
Projects were renamed to Opportunities
Campaigns were renamed to Initiatives.

However, the code for the Virtuous Volunteer API/Webhooks
will continue to use the terms
Projects and Campaigns.

As part of either the CRM Integrations Add-on or the API Access Add-on, you can subscribe to Virtuous Volunteer Webhooks to get updates on new events that happen in Virtuous Volunteer. We have made certain events available for subscription. All you need to do is enable the feature, enter in the Target URL, and choose which events you want to subscribe to. We will send over a payload with the data for each event to your target URL so that you can take the data and display it however you desire.

See screenshot and documentation below for more info.

1.png

Documentation

Permissions

Requests

  • POST requests are sent to your server at the provided URL for all configured events until disabled by an administrator.

Rate-limiting

  • We do not rate-limit webhook requests. If rate limiting is needed in your application, you must implement that functionality yourself.

Retries and Timeouts

  • When the URL to which we’re sending the webhook fails to send a response with a 2xx status code or when the timeout period (3 seconds) expires, Virtuous Volunteer will consider the call to be failed. We will retry failed requests 2 times, for a total of 3 tries. After the first failure we will retry the request after 10 seconds, and after another failed attempt we will send a final request after 100 seconds.

Payloads

  • Webhook payloads will consist of two important parts, the headers and the body.
  • The most important header will be the “vomo-signature” header. This will contain a hash of the body json and secret which is generated for you. The method for this is hash_hmac(‘sha256’, $payloadJson, $secret), which you can use in your application to verify the payload.
  • The body will contain an object with three top-level keys:
    • “type”: The type of event that triggered the webhook call. These will be formatted in the form of “object.action” or “object.public.action” for public events.
      • For example, a project updated webhook event will have the type of “project.updated”, and if you are subscribed to public projects, you would recieve a “project.public.updated” event.
    • “organization_id”: The Virtuous Volunteer organization ID that the webhook is being sent it -- in case there are multiple organizations using the same endpoint.
    • “data”: This is the Virtuous Volunteer object. The exact payload will vary by object.
  • For a list of the JSON payloads for each Webhook type, see the links below:

Related articles