🔒 The Webhook functionality is currently in its Beta testing phase. This means you may see some changes to the overall look and feel of things until its final release
Webhooks in Famly
As part of our commitment to building an open platform that supports seamless integration, we’ve developed Webhook functionality. This allows integrators to subscribe to specific events, triggering the Famly platform to send a request to a designated URL when those events occur. This enables external systems to react to changes in Famly and create deeper integrations.
💡 For example, if you register a webhook for invoice creation, Famly can send the invoice details to an external ERP system as soon as a new invoice is generated.
How Webhooks Work
The webhook system is asynchronous, meaning it processes events in the background. When an event occurs (e.g., when a new child is added), Famly checks if there are any registered webhooks for that event at the relevant site or organisation.
If webhooks exist, a request is queued and processed asynchronously. In most cases, this happens almost instantly, though minor delays are possible.
Technical details
Webhooks send POST HTTP requests to the specified URL
Requests include an HTTP header with a Sha256Hmac hash of the payload for verification (see instructions on validating requests below)
The receiving endpoint must respond within 10 seconds
If an HTTP error occurs, the request is retried up to five times using exponential backoff
Events, including payload and responses, are stored for 30 days and can be viewed in Famly
How to Subscribe to Webhooks
To subscribe to a webhook:
Open Famly
Go to Settings → Integrations → Webhooks
This feature must be enabled on your site, and you’ll need the appropriate permissions to manage it. If you don’t have access, contact support@famly.co.
In this list, you’ll see all registered webhooks. To add a new webhook, click Add webhook, then:
Select the events you want to subscribe to
Enter a name for the webhook
Provide the URL that should be called when the event occurs
Ensure the webhook is activated
For the Secret, enter a unique key that will be used to generate a hash of the payload. This allows you to verify that requests are genuinely coming from Famly.
Receiving Webhooks Calls
When a webhook is configured, Famly will make a POST request to the specified URL. The system will include the following headers (not a complete list), and values are just examples.
Content-Type:
application/jsonAccept-Encoding:
gzip, deflateUser-Agent:
Java-http-client/17.0.8X-Famly-Hmac:
24961ed7451342......a58713ad3ae066Content-Length:
527
The body of the request will vary depending on the event that triggered the webhook call.
An example of a payload is shown here:
{
"requestId": "01HBZQ60T0E834D3KCE7P3TVF3",
"eventId": "5dc5bfcf-59b6-46d2-a1c9-b9d41e9f61c7",
"siteSetId": "6d130c40-93aa-44c2-8f5b-3d52b310e34e",
"eventTime": "2023-10-05T10:47:21Z",
"operation": "Updated",
"objectType": "ChildEvent",
"data": {
"childId": "be0ea60c-1191-4dd2-8629-81793b6b83c3",
"name": {
"fullName": "API Test2 16112022",
"firstName": "API",
"middleName": "Test2",
"lastName": "16112022"
},
"gender": null,
"birthDay": "2022-11-02",
"startDate": "2022-11-16",
"endDate": null,
"groupId": "37626de8-c2dd-4f0b-af74-55387353e3ca",
"address": null
}
}
All events will have the following keys in the root object of the payload
requestID- A unique identifier for each request. If a request is retried, this will change between requests.eventId- A unique identifier for the given event. This will be the same across retries of the same event.siteSetId- A unique identifier (UUID) of the site or organization that this event relates to.eventTime- The time the event occurred. This might differ slightly from the time the event is dispatched due to queuing or retrying.operation- Most objects will be either:UpdatedCreatedDeleted
objectType- The type of object this relates to. At this time, the following types are supported:ChildBillPayerInvoiceContact
data
The structure of the "data" key will depend on the object type.
Validating Payload
The header X-Famly-HMAC contains a hash that can be used to validate the request. The signature is a hex-encoded SHA256 HMAC generated with the secret that was given when the webhook was registered.
An example of validating the HMAC is shown here using the CryptoJS framework:
var CryptoJS = require("crypto-js");
function verifySignature(payload, secret, expectedSignature) {
return webhookDigest(payload, secret) === expectedSignature;
}
const webhookDigest = (payload, secret) => {
const words = CryptoJS.HmacSHA256(payload, secret);
return CryptoJS.enc.Hex.stringify(words);
}
Viewing Webhook Events
To view the HTTP requests triggered by a webhook event, go to the registered webhook's settings by navigating to Settings → Integrations → Webhooks → Select webhook.
On this page, you can see all the requests, including the Request and Response Headers and Payload. You can also manually retry the request from this page.
