Hire Cancelled

This event is triggered when the job/hire for a worker is cancelled.

The payload includes a selection of objects with fields that allow you to identify the contract and the worker, so that you can update their status in your own system.

Webhook payload

The payload contains the following fields and objects:

{
    "event": "hireCancelled",
    "data": {
        "contract": {},
        "worker": {},
        "trustedContact": {},
        "customFieldValues": {},
        "cancelReason": {}
    }
}

Event Identifier

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

Event Data

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

The hire status information is included in the contract object as the hireStatus field, which contains the current status of the hire. For this event, it will always be "cancelled". This field provides a consistent way to track hire status across all hire-related webhook events.

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.
`hireId` is the ID that refers to the hire (or engagement) in the Worksome platform. This ID remains constant even when contract details are revised or updated, providing a stable reference for the overall engagement.
`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.
`hireStatus` is the current status of the hire at the time the webhook was triggered. Possible values are `draft` (hire has pending approval requests), `offered` (hire is not yet accepted by freelancer), `signed` (hire is accepted but contract period hasn’t started), `active` (contract period has started and hire is ongoing), `ended` (hire has completed naturally), `cancelled` (hire was cancelled), and `terminated` (hire was terminated early). This field provides a consistent way to track hire status across all hire-related webhook events.
`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`, or `remote-only`.
`terminatedReason` the reason for a contract being terminated early (only included when the event is `earlyTerminated`). Possible values are `worker_unavailability`, `project_completed_early`, `mutual_agreement_to_terminate`, `budget_constraints`, `change_in_project_scope`, `performance_issues`, `communication_issues`, `personal_reasons`, `legal_or_compliance_issues`, `violation_of_contract_terms`, `unforeseen_circumstances`, `dissatisfaction_with_quality_of_work`, `conflict_of_interest`, and `other`.

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.

Cancel Reason

The cancelReason object contains details about why the hire was cancelled.

`CancelReason` fields
`reason` always contains the string `custom` for cancelled hires.
`reason_message` contains the cancellation message provided by the user.

Payload example

{
    "event": "hireCancelled",
    "data": {
        "contract": {
            "id": "Q29udHJhY3Q6MTIzNA==",
            "hireId": "SGlyZToxNTY4NTA=",
            "accountId": "Q29tcGFueTo0MjAK",
            "hireStatus": "active",
            "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"
            }
        ],
        "cancelReason": {
            "reason": "custom",
            "reason_message": "Project requirements have changed significantly."
        }
    }
}