Youforce Webhooks

Introduction

Webhooks are a messaging mechanism that improves the integration experience between two systems by minimizing waiting times — making them especially well suited for integrations where immediate updates matter.

Unlike the classic API consumption model, where the consumer has to keep polling for changes, webhooks provide a reactive integration: the consumer simply waits for changes to arrive, resulting in a faster integration with minimal waiting times.

For example, when a mutation happens in HR Core — such as an update to the organization unit of a particular employment — our services send an HTTPS POST request to a web address you have configured in advance. This message includes detailed information about what happened, using a format similar to the domain APIs, so integrators can handle the information easily and consistently.

Youforce Webhooks Model

Like the Youforce APIs, webhooks are organized by domain. Each domain has its own webhook publisher with its own set of events. Applications can subscribe to one or more events through the Visma Developer Portal.

To receive events, you need to:

1. Subscribe to the correct event(s) from the Youforce Publisher application in the Visma Connect Developer Portal.
2. Provide the Client ID you created, so we can authorize you to receive those events.

Once subscribed, you will start receiving all matching changes as they occur.

For full details on integrating with webhooks and Visma Connect, see Webhook Dispatcher.

Security

Securing webhooks is essential for protecting your data flow. When your webhook subscription is set up, you receive a unique secret for that specific integration. This secret allows you to validate that a received webhook message genuinely came from our Webhook Dispatcher, and not from a third party.

Validation is done by verifying the X-VWD-Signature-V1 header included in every webhook message we send — this header contains the message encrypted with your secret.

For detailed implementation guidance, see Using a Webhook Secret.

Webhook Message Structure

A webhook message is structured data — in our case, JSON — describing a specific event and its relevant information.

Headers

The message header includes information provided by Visma Connect. The most relevant headers for our integration are:

Event types

The following event types can be received, each tied to a specific entity:

ASSIGNMENT_CHANGED, COSTALLOCATION_CHANGED, EMPLOYMENTEXTENSION_CHANGED, EMPLOYMENTWORKSCHEDULE_CHANGED, EMPLOYMENTTYPE_CHANGED, EMPLOYMENT_CHANGED, JOBPROFILE_CHANGED, LEAVEENTITLEMENTCHANGE_CHANGED, LEAVEENTITLEMENT_CHANGED, LEAVEHOURS_CHANGED, MATERNITYLEAVE_CHANGED, ORGANIZATIONALUNIT_CHANGED, PERSONEXTENSION_CHANGED, PERSON_CHANGED, ROLEASSIGNMENT_CHANGED, SALARYDETAIL_CHANGED, SICKLEAVE_CHANGED, WORKPATTERN_CHANGED

Payload fields

The information about the change itself is found in the body of the message:

Webhook Operations

Handling Update Operations

For Update operations, the changedFields object lists each changed field along with its oldValue and/or newValue, depending on the type of change. It is the integrator’s responsibility to interpret this information correctly.

Examples:

• If a new sick leave period is added, you’ll receive a SICKLEAVE_CHANGED webhook with operation: Update, where changedFields includes the new period only in newValue.
• If a sick leave period is removed, you’ll receive a SICKLEAVE_CHANGED webhook with operation: Update, where changedFields includes the removed period only in oldValue.

Duplicate or repeated webhooks

You may receive several webhooks for the same event and operation. When this happens, the message with the latest timestamp contains the most up-to-date, valid synchronization data.

Fields Not Present in the API Response

Some fields returned by the API are calculated fields that don’t originate from HR Core, so they are not included in the value field of a webhook message. This information can instead be derived from the webhook’s metadata:

Responding to Webhook Messages

• Always return an HTTP 200 status code once you’ve received and accepted the message. Returning 200 tells Visma Connect the message was delivered successfully and it will not be redelivered — what your system does with it afterward is entirely up to you.
• Messages must be processed within 5 seconds. If your endpoint doesn’t respond within this window, Visma Connect will assume something went wrong and will retry delivery.

Example: Update Operation

Example payload for an EMPLOYMENT_CHANGED event with operation: Update:

{
     "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": []
     }
}

Summary of Key Behaviors