Webhooks are a mechanism that allows Donorfy to notify another 'receiving' system when data has been added, changed or deleted.

This is an advanced feature - you may need programming skills or the help from a Donorfy partner to make use of this feature.

The receiving system must be capable of listening out for the notifications sent by Donorfy and handling the notifications when they are received. When a notification is received the receiving system will usually make a call to the Donorfy API to retrieve more information.

To set up a webhook go into Settings > Configuration > Webhooks,

press the Add Webhook button - see the example screen below - and enter

• a name for the webhook - this is to help you identify where the notifications are being sent
• the URL where the receiving system is listening for notifications
• whether operations from selected API permission should be ignored - see below for more information
• indicate when notifications should be sent - press Save Changes.

Your webhook will then be shown in the list of Existing Webhooks

Ignoring Operations from a selected API Permission

Often your webhook will work with an API permission - see article

If this is the case your webhook may need to ignore the API permission it works with.

This is to avoid an endless loop where a webhook notification is sent which triggers a receiving system to call the API, this call then triggers the sending of another notification which in turn triggers another API call which triggers another notification and so on.

Private Key

Donorfy will generate a 'Private Key' for your webhook - this key is used to create a unique hashed message authentication code which will be sent with every notification. This code allows you to check that the notification was sent by Donorfy - see below for more information.

You can change or delete your existing webhooks as needed.

What Does a Webhook Notification Contain?

When data is added, changed or deleted Donorfy will send the notification as an HTTP post operation to the URL in the webhook setup. The way notifications are processed means there may be a short delay - typically around a minute - between making a change in Donorfy and the notification being sent.

The notification will contain the following:

• MessageId - this is a unique identifier for the message 
• MessageType - this describes the operation that caused the notification to be sent - e.g. ConstituentChange - see the list below
• RelatedId - this is an id of the entity the message relates to - e.g. for a ConstituentUpdated this would contain the Id of the constituent that had been updated
• MessageToken - this a hashed message authentication code (HMAC) The message HMAC  uses SHA-256 as its message-digest algorithm, it is calculated from a combination of the MessageId, Message Type, RelatedId, and the Private Key. You can recalculate the message token and compare it with the value in the message to check the message is valid. For testing an online HMAC tester can be found here
• Data - this is an optional dictionary - ie. key/value pairs - which can contain further information 

MessageTypes 

Message types typically comprise a noun & verb - e.g. ConstituentUpdated, the

• Noun can be one of Constituent, Transaction, Activity, RecurringPaymentInstruction, GiftAid.
• Verb can be one of Add, Change, Delete

For constituents, the verb Merged may also be sent (i.e. ConstituentMerged) when two constituents are merged. The related id will contain the Id of the constituent that was merged - you can then call the constituents MergeTarget API endpoint to get the constituent the constituent was merged into.

Trying Out Webhooks

To try out the webhooks you can set up a listener (e.g. using Beeceptor or Webhook Tester) and send the webhook notifications to the URL of the listener - you can then view the contents of the notification messages.

The Donorfy API is a Professional-only feature. Essential subscribers, please contact us to find out more about upgrading.