Getting Started

Webhooks are a way to enable real-time notifications to third-party systems, for various events within the Worksome platform. This feature facilitates synchronizing your systems with our platform and ensures immediate updates.

The way a webhook works, is when a specific event happens in the Worksome platform, the platform automatically makes an HTTP request to a URL on your system. The request contains a payload in JSON format, with information relevant for this specific event.

In order for you to receive this webhook, you must supply an endpoint URL to your system, and we will agree on a secret token, that we use to sign the request.

Example

We have an event that triggers when a contract is accepted by a worker.

You have supplied an endpoint URL of https://api.example.com/worksome-webhook to us, and we have agreed on a secret tHizIsAnX@mp|E. We store this into the Worksome platform, along with information that you want to receive a webhook call when a worker has accepted a contract with your company.

Playing out the example, a worker now accepts the contract. This is what happens next:

  • The Worksome platform immediately makes an HTTP POST request to https://api.example.com/worksome-webhook containing a payload with a minimal set of information, which identifies the contract, the worker and relevant custom fields, if any.

    The request is signed using the secret and the signature is placed in a Signature header of the request. The signature can be used to verify that it is in fact Worksome who sent the webhook.

  • Your system receives our request at your endpoint and responds with an HTTP 200 code. You should verify it using the signature and secret, and then take any action you need at your end, such as storing it in your database and triggering any events you need.

    We provide a minimum of information in the webhook itself, so an action on your part might include calling our API for more information that you might need.

  • In case your system does not respond with an HTTP 2XX code, we will back off and retry the call later. We use an exponential backing off strategy.

Payload example

The payload could look something like this:

{
    "event": "contractAccepted",
    "data": {
        "contract": {
            "id": "Q29udHJhY3Q6MTIzNA==",
            "startDate": "2023-11-20",
            "endDate": "2024-02-20"
        },
        "worker": {
            "id": "V29ya2VyOjIzNDU2",
            "externalIdentifier": "d05fc13d-156e-4cc6-b325-a42e20f721c5",
            "name": "Peter Bishop",
            "email": "[email protected]",
            "phone": "+16955024"
        },
        "customFieldValues": [
            {
                "id": "Q3VzdG9tRmllbGRWYWx1ZToxMgo=",
                "customFieldTitle": "Manager",
                "displayValue": "Olivia Dunham"
            },
            {
                "id": "Q3VzdG9tRmllbGRWYWx1ZTo3Cg==",
                "customFieldTitle": "Client",
                "displayValue": "Massive Dynamic"
            }
        ]
    }
}

Breaking down this payload, we see the event field, which contains the event type that triggered the webhook. Your system may subscribe to several different events, so it must look at this field first, to handle the payload data correctly.

The data object contains the information relevant for the event.

For a contractAccepted event, we send basic information about the contract, the worker hired and custom fields tied to the hire.

The contract object contains the id of the contract, along with the start and end date.

The worker object contains the id of the worker in the Worksome platform, the (optional) externalIdentifier which is an identifier for the worker in your system, along with the name and email of the worker.

Finally, there is an array of customFieldValue objects with their id, custom field title and display value.

The id fields are the same as in the GraphQL API, so if you call the API for more information, these are the ID’s you must use in your queries.