IMPORTANT The recommended approach is use a "pull" implementation together with availability queries direct to the platform to get the best out of an updatedge API implementation.
If you wish to implement a "push" approach, you can configure the updatedge API to do this using a webhook. However, there are a number of caveats you need to be aware before approaching an implementation using this method.
Overview
The diagram below shows an implementation scenario.
Steps
- A worker shares their availability (makes changes to their timeline).
- updatedge calls your webhook implementation with a list of the events that had been created, updated or deleted in that "share" along with a timestamp of when the share was completed.
- Your system takes this data and insert/update/delete's an equivalent set of events within your system.
- Your queries then take this data into account when calculating worker availability.
Caveats
Retrieving A Worker's Entire Timeline
After you have successfully matched up an internal record on your own system with an updatedge worker (either by using the GetByEmail endpoint on it's own or in conjunction with the Worker Added Contact webhook) you will need to perform an initial pull for the worker's timeline events.
Without this, you will not have an up-to-date set of events for the worker going forward from the point of initial connection.
You can use the GetEvents API endpoint to do this, but you may only request events across periods of 31 days or less. You will need to loop repeatedly from the current date and time through the months ahead until you have downloaded the worker's entire timeline. You can retrieve the last event in their timeline using the GetFurthestEvent API endpoint to give you a reference point up to where you will need to pull.
Queuing Event Change Messages
While you retrieve all the initial events for a worker, you will need to temporarily store event change notifications from the Events Changed webhook until the process has completed. Although event change messages are queued in the order they are created on the updatedge platform before they are sent to consumers, each set of changes is dispatched asynchronously. This means if a worker shares multiple changes in quick succession there is a possibility you may receive these batches out of order within a few seconds of each other. To help with this, we include a timestamp in each message we send your webhook so that you can ensure you execute changes to events at your end in the correct order.
We are currently looking at ways we can guarantee message delivery to API implementers happens in the correct order. It is important to note, this scenario only happens if the worker performs multiple shares in an extremely short timeframe.
Webhook Traffic Load
As you connect more workers to your internal records, the amount of traffic being sent to your webhook will increase. You must ensure your system can handle this load and that it can accept data and queue it in the order it is received to ensure you apply updates in the order the worker is making them to your timeline.
Downtime / Interruptions in Service
Webhook message delivery is currently a fire and forget service. This means that if we dispatch a webhook message to your endpoint and it isn't received due to a connectivity issue at your end of a platform service issue at ours, the message is not re-delivered.
Therefore, a failed message delivery would result in the implementer's system needing to requery each worker's events to get an accurate snapshot of each worker's timeline.