⚠️ Important:
Webhooks are intended for advanced use cases. You may need development skills or support from a Donorfy partner to implement them correctly.
Understand What Webhooks Do
Webhooks allow Donorfy to notify another system when data changes.
Send notifications when data is added, changed, or deleted in Donorfy.
Allow a receiving system to react by calling the Donorfy API for more details.
📌 Note:
The receiving system must be capable of listening for HTTP POST requests and handling the payload securely.
Set Up a Webhook
You can configure webhooks directly in Donorfy.
Go to Settings, then click Configuration, then click Webhooks.
Click Add Webhook.
Enter a descriptive name to identify the webhook.
Enter the URL where the receiving system listens for notifications.
Choose whether operations from selected API permissions should be ignored.
Select which events should trigger notifications.
Click Save Changes.
The webhook will then appear in the Existing Webhooks list.
Avoid API Update Loops
Webhooks often work alongside API permissions.
⚠️ Important:
If a webhook reacts to API updates and then calls the API again, this can cause an infinite loop.
To prevent this:
Identify the API permission used by your integration.
Configure the webhook to ignore operations from that API permission.
This prevents Donorfy from sending webhook notifications for changes made by the same API.
Use the Webhook Private Key
Each webhook has a unique private key.
Use the private key to validate incoming webhook messages.
Generate a hashed message authentication code (HMAC) to confirm the message came from Donorfy.
You can regenerate or delete webhooks and private keys at any time if required.
Understand the Webhook Payload
Webhook notifications are sent as HTTP POST requests.
📌 Note:
There may be a short delay, typically around one minute, between a change in Donorfy and the webhook being sent.
Each notification includes:
MessageId: A unique identifier for the message.
MessageType: The event that triggered the notification.
RelatedId: The ID of the related entity in Donorfy.
MessageToken: An HMAC signature using SHA-256.
Data: Optional key-value pairs with additional information.
Validate Webhook Messages
To confirm a webhook message is valid:
Recalculate the HMAC using the MessageId, MessageType, RelatedId, and the webhook Private Key.
Compare your calculated value with the MessageToken received.
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
If the values match, the message is authentic.
Recognise Supported Message Types
Message types follow a consistent naming pattern.
The noun represents the entity:
Constituent
Transaction
Activity
RecurringPaymentInstruction
GiftAid
The verb represents the action:
Add
Change
Delete
For constituents, an additional verb is supported:
Merged, sent when two constituents are merged.
📌 Note:
For a ConstituentMerged message, use the MergeTarget API endpoint to identify the surviving constituent.
Test Webhooks Safely
You can test webhook behaviour using a temporary listener.
Create a test listener using a webhook testing tool.(e.g. using Beeceptor or Webhook Tester)
Configure your Donorfy webhook to send notifications to the test URL.
Perform actions in Donorfy and inspect the received payloads.
This allows you to validate structure and authentication before using a live system.
⚠️Important:
The Donorfy API is a Professional-only feature. Essential subscribers, please contact us to find out more about upgrading.