Events and Payloads

Summary

With your server up and running securely you'll want to start doing something useful with the information it's receiving. In this guide, we'll go over the structure and contents of the events that Youmanage will send to your server.

Payload Common Properties

Event payloads all follow a similar structure and an example payload is shown below:

{
   "Changes": {
      "JobLevel": {
         "Previous": "Director",
         "Next": "Employee"
      }
   },
   "Entity": {
      "Id": 11,
      "Manager": "Steven Rogers",
      "EmploymentEnd": null,
      "Title":"Mr",
      "OtherTitles": null,
      "FirstName": "Tony",
      "MiddleName": null,
      "LastName": "Stark",
      "MaidenName": null,
      "KnownAs": "Iron Man",
      "WorkPhone": null,
      "WorkMobile": null,
      "WorkEmail": "[email protected]",
      "Company": "Stark Industries",
      "Division": "Defence",
      "JobLevel": "Employee",
      "Location": "n/a",
      "Department": "n/a",
      "JobTitle": "Avenger",
      "EmployeeNumber": "0001",
      "ContinuousStart": "2017-01-01T00:00:00Z",
      "Started": "2017-01-01T00:00:00Z",
      "ContractEnd": null,
      "Status": "Former",
      "Type": "Full-Time"
   },
   "EntityType": "Employee",
   "Action": "Update",
   "OccurredAt": "2020-10-30T09:42:21Z",
   "IdempotencyKey": "50d70bab-d60f-4ab1-944f-f6e64d1e4e76"
}

Each payload message will always contain these common fields:

Entity

Full details of the state of the entity being acted upon after any actions or changes have been applied. This will be in the same format as if requested from the API. 

EntityType

This code defines the type of entity that the event describes. Each entity has its own unique entity type code, for example, when an employee entity is changed this field would show 'Employee'. The entity codes for each entity type can be found in the description for each endpoint in the API reference.

Action

Details the type of action that was undertaken for the entity. Common actions include: Create, Update and Delete, however, some entities may support additional actions.

OccurredAt

The time at which this event occurred, this can be used to reorder any events that are received out of order.

IdempotencyKey

This is a unique key that is assigned to each event and can be used to ensure that multiple requests for the same event will only be processed at most once.

If the action caused any changes to occur to the entity then an additional property Changes will be available.

Changes

This will list any properties on the entity that have been changed. It will also detail the value of each property before the change was applied (Previous) and the value after the change (Next)

Request Headers

In addition to the basic HTTP headers that are sent with requests, Youmanage will also send a couple of custom headers:

User-Agent

Webhook requests sent from Youmanage will always come with a user agent string starting with "YoumanageWebHook".

X-Youmanage-Signature

If you have secured your webhook with a secret then this additional header will be sent and will allow you to verify the request contents are from Youmanage and have not been tampered with.

Entity Definitions

In order to make things as easy as possible to get started the structure and formatting of entity information is exactly the same as if the entity were requested via the API and as such you can see detailed examples for each type of entity supported over in the API reference section.

Selecting Events

Now that you know the structure of events we'll talk about how to limit the events to only those that are useful for your integration. There are a few different scenarios that we'll go through one by one.

Select All

The simplest method for selecting events is to subscribe to all events and this can be done by checking the All box.

This will select all actions for all entities that are currently supported, and will also automatically start sending for entities and actions that are implemented in the future. Care should be taken when selecting all events as this can lead to a large amount of traffic being sent to your server.

Select Single

If your integration is only interested in a specific event then you can select that.

An event is broken down into two parts, the first being the type of object that has changed and the second, is the action that has been taken on the object. Most objects will have the Create, Update and Delete actions but may have more if there are specific processes that are undertaken.

If your integration is dealing with employee onboarding and is looking to get information about new employees created within Youmanage, then it could select only the event for employees being created which would be Employee:Create. You will need to untick the All checkbox before you will be able to enter a manual event selection in the textbox.

Select Multiple Actions

Following on from the previous example, your onboarding integration will likely need to also know about any employees who are removed from the system. Instead of creating a new webhook to send this information, we can extend the events that are selected by our current webhook.

Now we want both the Create and Delete actions to be sent for any Employees and this can be done by comma separating the actions giving us Employee:Create,Delete.

In addition to select all the actions for a given entity you can use the wildcard symbol (*). Like the all checkbox this will select all actions for the entity both currently implemented and any added in the future.

This becomes useful when combining specific entities which we'll go into more detail with next.

Select Multiple Entities

The last tool in the box is selecting multiple different entities and their actions.

Adding to our onboarding integration you may want to know about any absences that are created for a new employee. You could select the all events option but this could put unnecessary load on your server.

Instead you can chain together multiple entity selections by separating them with a semi-colon (;).

For our final example, we want to select Employees who are Created or Deleted and any Absences that have been created which would give us the following event selection criteria - Employee:Create,Delete;Absence:Create

Using these examples you should be able to create an event criteria to suit any combination of events and actions.

This concludes our tutorial series on Webhooks.

You should now have all the information required to get started on your next integration with Youmanage!