Webhooks allow Folks to automatically send information to an external system when an employee-related event occurs. They are used to capture these changes in real time to power integrations or automations.
Scope : webhooks are currently limited to the HRIS module and can only be managed by a company administrator. The feature must be activated by Folks.
Activation and access
-
If the feature is activated :
Go to Settings > Integrations > Webhooks. -
If the feature is not visible :
contact Folks support or your Customer Success representative to request activation.
The Webhooks page becomes visible only to administrators once the company setting is activated.
Webhook configuration
The form for creating or modifying a webhook includes the following fields :
| Field | Description | Required |
|---|---|---|
| Name | Internal name of the webhook | Yes |
| URL | HTTPS endpoint receiving POST requests | Yes |
| Enabled | Enables or suspends webhook sending | Yes |
| Events | List of triggering events | Yes (at least one) |
Validation rules for the "Name" field
- Required
- Maximum length : 255 characters
- Unique name (no duplicates allowed)
-
Must not end with a period (
.) - Must not start or end with a space
-
Allowed characters : alphanumeric, space, hyphen (
-), underscore (_) -
Forbidden characters :
< > : " / \ | ? *
Validation rules for the "URL" field
- Required
- Maximum length : 2000 characters
-
Must start with
https:// -
localhostforbidden in production environment
Event selection
Each option in the interface corresponds to a type of event transmitted in the payload (value of the event field).
| Interface |
event Value
|
Description |
|---|---|---|
| Created |
employee.created
|
New employee |
| Updated |
employee.updated
|
Modification of an employee's data |
| Departure |
employee.offboarded
|
Offboarding / deactivation |
| Return |
employee.returned
|
Return after absence |
| Manager Assignment / Change |
employee.manager.assigned
|
Newly assigned or modified manager |
| Status Change |
employee.status.changed
|
Active, inactive, on leave, etc. |
Note : if no event is selected, no webhook will be sent.
Payload structure
Webhooks send a JSON payload containing the following fields :
| Field | Required | Description |
|---|---|---|
event
|
Yes | Event type |
employee_id
|
Yes | Folks identifier |
email
|
Yes | Employee's work email |
changes
|
No |
Details of modified fields, in the format { old, new }
|
timestamp
|
Yes | Sent date and time (ISO 8601) |
effective_date
|
No | Effective date of the change |
source
|
Yes |
Always folkshr
|
version
|
Yes |
Payload format version (currently 1.0)
|
environment
|
Yes |
Always production on the client side
|
Specificity : during the employee.created event, the payload contains all of the employee's data.
Payload example
{
"event": "employee.updated",
"employee_id": "F12345",
"email": "jonathan.pelletier@mycompany.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"
}System behavior
- Delivery : fire and forget model.
- Retries : 3 attempts, spaced 2 minutes apart in case of failure.
- Traceability : full logging history of sends (successes and failures).
-
Sensitive data protection :
sensitive values in
changesare masked by"*****". - Authentication : each request includes a mandatory authentication token, which the receiving system must verify.
-
environmentfield : internal informational field, alwaysproductionfor clients.