Webhook Events

Worksome offers a selection of webhooks intended to allow you to keep your systems in sync with your data in the Worksome platform.

We intentionally provide a minimum of information in the webhook payloads themselves. If you need more, we refer to calling the GraphQL Public API after you receive the webhook.

The payload includes IDs for objects that can be looked up in the Public API.

Worksome sends 17 event types. The event field in every payload carries the identifier in the middle column — subscribe to the identifier, not the display name.

Hires and contracts

Event Identifier Triggered when
Contract Accepted contractAccepted A worker accepts a contract.
Hire Accepted hireAccepted Never delivered — see the note below.
Hire Updated hireUpdated A hire or one of its related objects changes.
Hire Cancelled hireCancelled A hire is cancelled before it became active.
Hire Ended hireEnded A hire reaches its natural end.
Hire Terminated hireTerminated A hire is ended early with a termination reason.

Talent pool

Event Identifier Triggered when
Trusted Contact Updated trustedContactUpdated A trusted contact changes — contact details, skills, and so on.

Payment requests

Event Identifier Triggered when
Payment Request Issued paymentRequestIssued A payment request is issued.
Payment Request Approved paymentRequestApproved A payment request is approved.
Payment Request Rejected paymentRequestRejected A payment request is rejected.
Payment Request Paid paymentRequestPaid A payment request is paid by the company.
Payment Request Cancelled paymentRequestCancelled A payment request is cancelled.
Payment Request Worker Paid Out paymentRequestWorkerPaidOut A worker has been paid out for a payment request.
Payment Request Recruiter Paid Out paymentRequestRecruiterPaidOut A recruiter has been paid out for a payment request.

Invoicing

Event Identifier Triggered when
Invoice Created invoiceCreated An invoice is created.
Invoice Paid invoicePaid An invoice is paid.
Credit Note Created creditNoteCreated A credit note is created.

Warning

hireAccepted is subscribable but never sent. The value exists in the subscription list, but nothing in the platform emits it: when a worker accepts, the hire-accepted handler sends contractAccepted instead. Subscribe to contractAccepted for that moment, and do not wait on hireAccepted.

Hire lifecycle events overlap

contractAccepted, hireUpdated, and hireEnded can fire around the same moment, because accepting a contract also changes the hire. Do not treat any single one as “the” signal that an engagement started:

  • Read contract.hireStatus from the payload rather than inferring status from which event arrived.
  • Make handlers idempotent, since more than one event may describe the same state change. See Handle Webhooks.
  • A hire the worker has accepted is ready until its start date passes, and only then active.