At Virtuous, we believe in playing well with others. That's why we have a robust API that allows for seamless integration with other systems.
While the API is an excellent way to access data in bulk, on a set schedule, webhooks provide access to real-time data updates in Virtuous, allowing you to seamlessly sync data with other platforms and maintain up-to-date records.
To configure webhooks, hover over the left side bar, then select Settings. Under Settings, select All Settings.
To create a new webhook, click the "Create a Webhook" button.
This will bring up the new webhook form.
In order to create webhook, you must provide a valid url where data will be posted. Be sure to include a complete url.
For additional security, you may opt to include a Secret key that will be sent as a header with each post, to confirm that data is being sent from Virtuous. The signature is generated by hashing the Secret AND the body of the payload using the HMACSHA256 algorithm and is formatted as a Base64 string.
Next, you'll have a choice to subscribe to all webhook events or select specific events. Webhooks are currently available for:
- Contact Create - receive an update any time a new Contact is added to Virtuous
- Contact Update - receive an update when data for an existing Contact is changed (for example, a new phone number is added)
- Contact Note Create - receive an update any time a new Contact Note is added to Virtuous
- Contact Note Update - receive an update when data for an existing Contact Note is changed
- Contact Note Delete - receive an update any time an existing Contact Note is deleted
- Event Create - receive an update any time a new Event is added to Virtuous
- Event Update - receive an update when data for an existing Event is changed
- Event Delete - receive an update any time an existing Event is deleted
- Form Submission - receive an update when a Form is submitted
- Gift Create - receive an update any time a new Gift is added to Virtuous
- Gift Update - receive an update any time data for an existing Gift is changed
- Gift Delete - receive an update any time an existing Gift is deleted
- Project Create - receive an update any time a new Project is added to Virtuous
- Project Update - receive an update any time data for an existing Project is changed
- Project Delete - receive an update any time an existing Project is deleted
To receive webhooks for all events, select "Send me everything" (this is the default option). To receive only certain webhooks, select "Let me select specific events" and then click on the checkbox by each event you wish to receive.
In order to receive webhooks, make sure the "Active" box is checked. If a webhook is no longer needed, it can be deactivated at any time.
Working With Webhooks
When an event occurs for which there is an active webhook, a payload will be sent immediately to the specified url. This means that if you have an active Gift Create webhook, you may receive several webhooks any time a Gift import is processed. Make sure your system is able to handle the volume of webhooks for these events.
Webhook payloads are sent in JSON format. Here is a sample Contact Create payload:
{
"contact": {
"referenceId": null,
"id": 397824,
"contactType": "Household",
"customContactType": null,
"isPrivate": false,
"isArchived": false,
"name": "Dr Stephen Strange",
"informalName": null,
"description": null,
"website": null,
"anniversaryMonth": null,
"anniversaryDay": null,
"mergedIntoContactId": null,
"customFields": {
"Board Term Start": null,
"Board Term End": null,
},
"contactIndividuals": [
{
"id": 483140,
"prefix": "Dr",
"firstName": "Stephen",
"middleName": null,
"lastName": "Strange",
"suffix": null,
"birthMonth": null,
"birthDay": null,
"birthYear": null,
"gender": "Male",
"isPrimary": true,
"isDeceased": false,
"customFields": {
"Treasurer": null,
"Volunteer": null,
"Willing to be a Solicitor": null
},
"contactMethods": [
{
"id": 384609,
"type": "Primary Email",
"value": "strange@marvel.com",
"isOptedIn": false,
"isPrimary": true
},
{
"id": 384610,
"type": "Mobile Phone",
"value": "212-995-5120",
"isOptedIn": false,
"isPrimary": true
}
]
}
],
"contactAddresses": [
{
"id": 547336,
"label": "Home",
"address1": "177 Bleecker St",
"address2": null,
"city": "New York",
"state": "NY",
"postal": "10012-1442",
"country": "US",
"isPrimary": true
}
],
"contactReferences": []
},
"event": "ContactCreate",
"eventId": "ea8e08ff-09ae-4aa6-9d2b-4b68fa56298c",
"eventDateTimeUtc": "2019-12-05T18:23:17.2141719Z",
"organization": {
"id": 000000,
"name": "Virtuous Sample Organization"
},
"organizationUser": {
"id": 000000,
"emailAddress": "sample@virtuoussoftware.com"
}
}
All webhooks can be reviewed on the Manage Webhooks screen. Click on the Edit icon to the right of any webhook to make changes to the configuration, including updating the payload url or the selected events.
From the edit screen, you can also review the webhook history, including payloads and responses. Use the tabs in the upper left to toggle between successfully delivered webhooks or to review failed webhooks. Click on the event ID for any successful webhook to view the payload and response.
Troubleshooting Webhooks
In the event that webhook delivery fails, Virtuous will automatically retry up to five times over a 24-hour period. When viewing failed webhooks, a counter to the right in red will display the number of attempts made. To retry any failed webhook, just click on the refresh icon to the right.
Now you are all set to start getting data updates from Virtuous!
Comments
0 comments
Article is closed for comments.