Introduction
Webhooks are like automatic messengers that let one system know when something happens in another. Instead of a program constantly asking, “Has anything happened yet?”, the webhook sends a notification in real time when something important occurs.
For example, when an employment changes in BO4 (like an update in the organization unit), our services send a message through an HTTP POST to a web address you have set up in advance. This message includes detailed information about what happened, using a similar format to the domain APIs. This way, developers can handle the information easily and consistently.
Unlike the APIs where you have to check over and over if there were any changes (which made things slower), webhooks send these updates much faster, usually within a few minutes. Because of this, delays are avoided and systems can work together more quickly and efficiently.
Youforce webhooks
The Youforce webhooks, like the APIs, are divided into domains. Each domain has its own webhook publisher with events. Applications can subscribe to one or more events in the Visma Developer Portal.
If you want to know how to integrate with webhooks and more details about Visma Connect, refer to the section: Webhook Dispatcher
Webhook security
Securing webhooks is crucial for protecting your data flow. When your Webhook subscription is setup, you will receive a unique “secret” for that particular subscription. Our Webhooks include the ability to use this received “secret” to validate that the published message was really sent from our Webhook Dispatcher. There is a header called “X-VWD-Signature-V1” along with each of our published Webhook requests.
For detailed guidance on implementing this measure, refer to the section Using a Webhook Secret.
Webhook message
A webhook message is composed of structured data, in our case in JSON format, detailing the specific event and relevant information.
In the header of the message, you will find some information provided by Visma Connect. The most relevant for our integration are:
- “X-Vwd-Event-Id”: “entity _CHANGED” - Type of event that we are sending, usually associated to an entity to indicate which type of record is impacted. For example: EMPLOYMENT_CHANGED or ASSIGNMENT_CHANGED
- “X-VWD-Signature-V1”: “teLIZbhIjwd065G5Grr0fvRrir+nJi9KG/C4aQ=” - Message encrypted with the secret provided in Visma Connect so you can check the integrity of the message
The information related to the webhook itself can be found in the content of the event.
Useful information in the payload:
- id: identificator of the record that is impacted by the event
- operation: type of operations made over the record. Posible values:
- Insert
- Update
- Delete
- changedFields: in case of an ‘Update’ operation, a list of fields that are impacted with a change will be shown
- timestamp: date and time of when the event has been processed in the API’s side
- value: updated content of the record. For more details about this content, please, check the section “Domain API’s”
There are some fields that are shown in the output of the api that are not shown in the value field of the webhooks. These fields are calculated ones which don’t bring any information from the core BO4. However, this information can be found in the metadata of the webhook message:
- isDeleted/isActive: this information can be found in the operation of the message. If the operation is ‘Deleted’ then the record has status isDeleted=true/isActive=false.
- latestSync: this field shows when the information was synchronized with the api.
Note: For updates within the value of the record, you will receive an operation type ‘update’, showing in the field ‘changedFields’ the old or new values depending on the action and it’s the integrator the one in charge of interpreting this information. For example:
- if there is a new sickleave period, you will receive a webhook of type “SICKLEAVE_CHANGED”, with operation ‘update’, including in the ‘changedFields’ the new period that has been added within the ‘newValue’ only.
- if a sickleave period is removed, you will receive a webhook of type “SICKLEAVE_CHANGED”, with operation ‘update’, including in the ‘changedFields’ the old period that has been removed within the ‘oldValue’ only.
Example of an Update operation for a “PERSON_CHANGED” type of event:
{
"id": "843847 5",
"operation": "Update",
"tenantId": "123456",
"changedFields": {
"hireDate": {
"oldValue": "2025-07-03",
"newValue": "2024-07-03"
},
"contractType": {
"oldValue": "4163",
"newValue": "6262"
},
"contractTypeName": {
"oldValue": "Contract Type",
"newValue": "Contract Type ED"
},
"workingAmount.amountOfWork": {
"oldValue": 62690.0,
"newValue": 40.0
},
"originalHireDate": {
"newValue": "2023-07-03"
},
"dischargeDate": {
"newValue": "2030-07-03"
}
},
"timestamp": "2025-07-03T10:12:35.4877275+00:00",
"value": {
"id": "843847 5",
"personCode": "843847",
"personId": "843847",
"contractCode": "5",
"validFrom": "1900-01-01",
"validUntil": "9999-12-31",
"employmentCode": "5",
"contractId": "5",
"originalHireDate": "2023-07-03",
"hireDate": "2024-07-03",
"dischargeDate": "2030-07-03",
"company": "23625 101",
"employmentType": "327",
"employmentTypeName": "Employment Type",
"contractType": "6262",
"contractTypeName": "Contract Type ED",
"jobProfile": "518869",
"jobProfileName": "Job Profile",
"organizationUnit": "94649",
"payrollInstitutionCode": "101",
"payrollClientCode": "23625",
"payrollRegistrationNumber": "1",
"classification": "7194",
"classificationName": "Classification Code",
"emailAddresses": [],
"phoneNumbers": [],
"organizationUnitCode": "OrgUnit",
"organizationUnitName": "Organization Unit",
"workingAmount": {
"amountOfWork": 40.0,
"parttimePercentage": 100.0,
"unitOfWork": "Hours",
"periodOfWork": "Week"
},
"extensions": []
}
}