Hire Updated

This event has a general purpose and triggers whenever a hire or it’s related objects are updated.

The following changes on a hire and related objects will trigger the event:

  • The job offer is accepted by Worker
  • Changes to contract is accepted by worker
  • The contract type on the hire is changed
  • The hire is ended
  • A staffing agency is attributed the hire
  • The hire changed from status “draft” to “active”,
  • The Worker information was updated (see Trusted Contact Updated below)
  • Custom field values on the related job was added or updated

Webhook payload

The payload contains the following fields and objects:

{
    "event": "hireUpdated",
    "data": {
        "contract": {},
        "worker": {},
        "trustedContact": {},
        "customFieldValues": {}
    }
}

Event Identifier

The event field contains hireUpdated as the identifier for this webhook.

Event Data

The data object contains the contract, worker, trustedContact and customFieldValues objects for the event.

Contract Object

The contract object has fields identifying the contract and the most important details.

Fields named here are always present.

Contract fields
id is the ID that refers to the contract in the Worksome platform, and you can query the API for the full details using this ID.
accountId is the ID that refers to the company account in the Worksome platform, and you can query the API for the full details using this ID.
startDate is the date (YYYY-MM-DD) that the contract starts or started. This field can be null if a start date is not known. The field has no time part.
endDate is the date (YYYY-MM-DD) that the contract ends or ended. This field can be null if the end date is not known. The field has no time part.
workerAcceptedAt is the time (YYYY-MM-DD HH:mm:ss CET) for when the contract is accepted by the hired worker. This field is null until the contract is accepted.
currency is the currency value for the rate on the contract. The values follow ISO 4217 format.
rate is the offered pay rate for the worker on the contract.
rateType defines the payment frequency that applies to the rate. Values are “hourly”, “daily”, “monthly”, or “fixed”.
jobOwners is a list of users that are assigned as owners on the related job (ID, name, email address). This list will be empty until a job owner is added.
jobId is the ID that refers to the job in the Worksome platform, and you can query the API for the full details using this ID.
jobName is name of the job as agreed on for the contract. Note that this can be different from the related original job post.
jobDescription is the full job description and scope for the contract. Note that this can be different from the related original job post.
purchaseOrderNumber is purchase order number (PO) that will be applied to all invoices from the hire.
locationPreference is the location preference of the contract. Possible values are “onsite-only”, “onsite-some”, “remote-only”.

Worker Object

The worker object has fields identifying the worker and most important details.

Fields named here are always present.

Worker fields
id is the ID that refers to the worker in the platform. You can query the API for the full details using this ID.
name is the full name of the worker.
firstName is the first name of the worker.
lastName is the last name of the worker.
middleName is the middle name of the worker.
email is the email for the worker.
phone is the phone number of the worker.
location is the location of the Worker as an object. The object includes name, address, city, zipcode, country, county, state.
businessEntity is details for the Worker’s business entity as an object. The object includes entity_type, label, company_no, company_name and tax_no.

Trusted Contact Object

The trustedContact object has fields with the worker’s data in relation the client.

Fields named here are always present.

Trusted Contact fields
id is the ID that refers to the trusted contact in the Worksome platform, and you can query the API for the full details using this ID.
accountId is the ID that refers to the company account in the Worksome platform, and you can query the API for the full details using this ID.
externalIdentifier is an identifier associated with the trusted contact from an external system. This may be null if no external identifier is defined.
status is the status of the invitation to the talent pool. Possible values are “invited”, “accepted”, “declined”.

Custom Field Value Object

The customFieldValue object has fields for the custom field values.

CustomFieldValue object fields
id is the ID referring to a particular value.
slug is a technical identifier for the field, based on the field title. This may be null if no slug has been set.
customFieldTitle is the title of the custom field.
displayValue is the human-readable representation of the custom field value chosen for this event.

The array is always present, but may be empty. Objects in the array always have the named fields.

Payload example

{
    "event": "hireUpdated",
    "data": {
        "contract": {
            "id": "Q29udHJhY3Q6MTIzNA==",
            "accountId": "Q29tcGFueTo0MjAK",
            "startDate": "2023-11-20",
            "endDate": "2024-02-20",
            "workerAcceptedAt": "2024-11-19 10:41:34",
            "currency": "USD",
            "rate": "550",
            "rateType": "daily",
            "status": "active",
            "jobOwners": [],
            "jobId": "Sm9iOjc5MTMK",
            "jobName": "Project Coordinator",
            "jobDescription": "The Project Coordinator is responsible for overseeing the successful planning, execution, and closure of projects within the organization.",
            "purchaseOrderNumber": "BA-1234-5678",
            "locationPreference": "remote-only"
        },
        "worker": {
            "id": "V29ya2VyOjIzNDU2",
            "name": "Peter Bishop",
            "firstName": "Peter",
            "lastName": "Bishop",
            "middleName": "",
            "email": "[email protected]",
            "phone": "+16955024",
            "location": {
                "name": "Home address",
                "address": "150 Maplewood Drive, Suite 200",
                "city": "Springfield",
                "zipcode": "62704",
                "country": "US",
                "county": "",
                "state": "IL"
            },
            "businessEntity": {
                "entity_type": "common_business",
                "label": "Bishop Ltd.",
                "company_no": "987654321",
                "company_name": "Bishop Ltd.",
                "tax_no": "ST-1234567890"
            }
        },
        "trustedContact": {
            "id": "VHJ1c3RlZENvbnRhY3Q6MzA=",
            "accountId": "Q29tcGFueTo0MjAK",
            "externalIdentifier": "d05fc13d-156e-4cc6-b325-a42e20f721c5",
            "status": "invited"
        },
        "customFieldValues": [
            {
                "id": "Q3VzdG9tRmllbGRWYWx1ZToxMgo=",
                "slug": "manager",
                "customFieldTitle": "Manager",
                "displayValue": "Olivia Dunham"
            },
            {
                "id": "Q3VzdG9tRmllbGRWYWx1ZTo3Cg==",
                "slug": "client",
                "customFieldTitle": "Client",
                "displayValue": "Massive Dynamic"
            }
        ],
    }
}