Les webhooks permettent à Folks d’envoyer automatiquement des informations vers un système externe lorsqu’un événement lié à un employé survient. Ils servent à capter ces changements en temps réel pour alimenter des intégrations ou automatisations.
Portée : les webhooks sont actuellement limités au module SIRH et ne peuvent être gérés que par un administrateur de compagnie. La fonctionnalité doit être activée par Folks.
Activation et accès
-
Si la fonctionnalité est activée :
Accédez à Paramètres > Intégrations > Webhooks. -
Si la fonctionnalité n’est pas visible :
contactez le support Folks ou votre représentant Succès Client pour demander l’activation.
La page Webhooks devient visible uniquement pour les administrateurs lorsque le paramètre de compagnie est activé.
Configuration d’un webhook
Le formulaire de création ou de modification d’un webhook inclut les champs suivants :
| Champ | Description | Obligatoire |
|---|---|---|
| Nom | Nom interne du webhook | Oui |
| URL | Endpoint HTTPS recevant les requêtes POST | Oui |
| Activé | Active ou suspend l’envoi du webhook | Oui |
| Événements | Liste des événements déclencheurs | Oui (au minimum un) |
Règles de validation du champ « Nom »
- Obligatoire
- Longueur maximale : 255 caractères
- Nom unique (aucun doublon autorisé)
-
Ne doit pas se terminer par un point (
.) - Ne doit pas commencer ou finir par un espace
-
Caractères autorisés : alphanumériques, espace, tiret (
-), underscore (_) -
Caractères interdits :
< > : " / \ | ? *
Règles de validation du champ « URL »
- Obligatoire
- Longueur maximale : 2000 caractères
-
Doit commencer par
https:// -
localhostinterdit en environnement production
Sélection des événements
Chaque option de l’interface correspond à un type d’événement transmis
dans
le payload
(valeur du champ event).
| Interface |
Valeur event
|
Description |
|---|---|---|
| Créé |
employee.created
|
Nouvel employé |
| Mis à jour |
employee.updated
|
Modification des données d’un employé |
| Départ |
employee.offboarded
|
Offboarding / désactivation |
| Retour |
employee.returned
|
Retour après absence |
| Attribution / changement du gestionnaire |
employee.manager.assigned
|
Gestionnaire nouvellement attribué ou modifié |
| Modification du statut |
employee.status.changed
|
Actif, inactif, en congé, etc. |
Remarque : si aucun événement n’est sélectionné, aucun webhook ne sera envoyé.
Structure du payload
Les webhooks envoient un payload JSON contenant les champs suivants :
| Champ | Obligatoire | Description |
|---|---|---|
event
|
Oui | Type d’événement |
employee_id
|
Oui | Identifiant Folks |
email
|
Oui | Courriel professionnel de l’employé |
changes
|
Non |
Détails des champs modifiés, sous la forme { old, new }
|
timestamp
|
Oui | Date et heure d’envoi (ISO 8601) |
effective_date
|
Non | Date d’entrée en vigueur du changement |
source
|
Oui |
Toujours folkshr
|
version
|
Oui |
Version du format de payload (actuellement 1.0)
|
environment
|
Oui |
Toujours production côté clients
|
Spécificité : lors de l’événement employee.created,
le
payload contient
l’ensemble des données de l’employé.
Exemple de payload
{
"event": "employee.updated",
"employee_id": "F12345",
"email": "jonathan.pelletier@monentreprise.com",
"changes": {
"last_name": { "old": "PELETIER", "new": "PELLETIER" },
"address_line1": { "old": "8 RUE ST-AUGUSTAIN", "new": "8 RUE ST-AUGUSTIN" },
"mobile_phone": { "old": "418 932 3221", "new": "418 932 4221" }
},
"timestamp": "2025-08-11T14:32:00Z",
"effective_date": "2025-08-11",
"source": "folkshr",
"version": "1.0",
"environment": "production"
}Comportement du système
- Livraison : modèle fire and forget.
- Retries : 3 tentatives, espacées de 2 minutes en cas d’échec.
- Traçabilité : historisation complète des envois (succès et échecs).
-
Protection des données sensibles :
les valeurs sensibles dans
changessont masquées par"*****". - Authentification : chaque requête inclut un token d’authentification obligatoire, que le système récepteur doit vérifier.
-
Champ
environment: champ informatif interne, toujoursproductionpour les clients.