🔒 Die Webhook-Funktion befindet sich aktuell in der Beta-Phase. Das bedeutet, dass sich einzelne Ansichten oder Abläufe bis zur finalen Version noch leicht verändern können.
Was sind Webhooks?
Webhooks sind eine Möglichkeit, Famly mit anderen Systemen zu verbinden. Sie sorgen dafür, dass bestimmte Aktionen in Famly (z. B. eine neue Rechnung oder ein neu angemeldetes Kind) automatisch an ein externes System weitergemeldet werden. So können z. B. Buchhaltungssysteme oder andere Plattformen automatisch reagieren – ohne manuelle Eingaben.
💡 Beispiel: Sobald in Famly eine neue Rechnung erstellt wird, kann diese automatisch an euer Abrechnungssystem gesendet werden – ganz ohne zusätzlichen Aufwand.
So funktionieren Webhooks
Das Webhook-System arbeitet asynchron, d. h. Ereignisse werden im Hintergrund verarbeitet.
Wenn ein Ereignis eintritt (z. B. ein neues Kind wird hinzugefügt), prüft Famly, ob für dieses Ereignis Webhooks registriert sind – entweder für die Einrichtung oder die Organisation.
Wenn entsprechende Webhooks existieren, wird eine Anfrage in die Warteschlange gestellt und asynchron verarbeitet. In der Regel erfolgt dies nahezu in Echtzeit, kleinere Verzögerungen sind jedoch möglich.
Technische Details
Webhooks senden HTTP POST-Anfragen an die angegebene URL
Die Anfrage enthält einen HTTP-Header mit einem SHA256 HMAC-Hash des Payloads zur Verifizierung
Der empfangende Endpunkt muss innerhalb von 10 Sekunden antworten
Bei einem HTTP-Fehler erfolgt ein erneuter Zustellversuch – bis zu fünfmal, mit exponentiellem Backoff
Alle Ereignisse – inklusive Payload und Antwort – werden für 30 Tage gespeichert und sind in Famly einsehbar
So abonnierst du Webhooks
Öffne Famly
Gehe zu Einstellungen → Integrationen → Webhooks
Diese Funktion muss für deinen Standort aktiviert sein und du benötigst entsprechende Berechtigungen. Wenn du keinen Zugriff hast, kontaktiere unseren Support über den In-App-Chat oder per E-Mail an support@famly.de.
In der Liste siehst du alle registrierten Webhooks.
Um einen neuen hinzuzufügen, klicke auf Webhook hinzufügen und:
Wähle die Ereignisse aus, die überwacht werden sollen
Vergib einen Namen für den Webhook
Gib die URL an, die beim Eintreten des Ereignisses aufgerufen werden soll
Stelle sicher, dass der Webhook aktiviert ist
Trage beim Feld „Geheimer Schlüssel“ einen eindeutigen Schlüssel ein, der zur Erstellung des Payload-Hashes verwendet wird
So kannst du überprüfen, ob die Anfragen tatsächlich von Famly stammen
Empfang von Webhook-Aufrufen
Sobald ein Webhook eingerichtet ist, sendet Famly bei Eintreten eines Ereignisses automatisch eine POST-Anfrage an die hinterlegte URL. Diese Anfrage enthält unter anderem folgende HTTP-Header (Beispielwerte):
Content-Type:
application/jsonAccept-Encoding:
gzip, deflateUser-Agent:
Java-http-client/17.0.8X-Famly-Hmac:
24961ed7451342......a58713ad3ae066Content-Length:
527
Der Inhalt der Anfrage (Payload) hängt vom jeweiligen Ereignis ab, z. B. ob ein neues Kind hinzugefügt oder eine Rechnung geändert wurde.
Beispiel für einen Payload:
{
"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
}
}
Alle Ereignisse enthalten im Hauptteil (Root-Objekt) des Payloads folgende Schlüssel:
requestId – Eine eindeutige Kennung für jede einzelne Anfrage. Wenn eine Anfrage erneut gesendet wird (z. B. bei einem Fehler), ändert sich diese ID.
eventId – Eine eindeutige Kennung für das jeweilige Ereignis. Sie bleibt bei Wiederholungen desselben Ereignisses gleich.
siteSetId – Eine eindeutige Kennung der Einrichtung oder Organisation, auf die sich das Ereignis bezieht.
eventTime – Der Zeitpunkt, zu dem das Ereignis eingetreten ist. Dieser kann leicht vom Versandzeitpunkt abweichen, z. B. durch Warteschlangen oder erneute Zustellung.
operation – Gibt an, was mit dem Objekt passiert ist. Meist handelt es sich um:
Created (erstellt)
Updated (aktualisiert)
Deleted (gelöscht)
objectType – Der Typ des betroffenen Objekts. Aktuell werden folgende Typen unterstützt:
Child (Kind)
BillPayer (Rechnungszahler:in)
Invoice (Rechnung)
Contact (Kontakt)
data – Die Struktur dieses Schlüssels hängt vom jeweiligen Objekttyp ab und enthält die inhaltlichen Details des Ereignisses.
Validierung des Payloads
Der Header X-Famly-HMAC enthält einen Hash, mit dem du die Anfrage verifizieren kannst. Dabei handelt es sich um einen hex-kodierten SHA256 HMAC, erzeugt mit dem bei Registrierung des Webhooks angegebenen geheimen Schlüssels.
Beispiel zur HMAC-Validierung mit CryptoJS:
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);
}
Webhook-Ereignisse einsehen
Um HTTP-Anfragen einzusehen, die durch ein Webhook-Ereignis ausgelöst wurden:
Gehe zu Einstellungen → Integrationen → Webhooks
Wähle den entsprechenden Webhook aus
Auf dieser Seite kannst du alle Anfragen einsehen - einschließlich der Anfrage- und Antwort-Header sowie des Payloads. Du kannst von hier aus auch eine Anfrage manuell erneut senden.
