Events are notifications that transporters provide from the time of booking until the shipment is considered done. Skrym receives events from transporters in one of two different ways:
Webhook
Getting events by Webhook means that Skrym will subscribe to the transporter's events on your behalf.
As soon as the transporter has a new event, it will notify Skrym who stores and parses
the event.
This is the preferred and more modern way of sharing tracking information, and tends to be the standard among
newer transporters.
Skrym also enables you to use this mechanism to subscribe to all your events (regardless of transporter) - you can read more on the Subscribe page.
Polling
Most transporters still do not provide webhook support, which means Skrym has to call the transporter's tracking API with regular time intervals in
order to know what is going on with a shipment.
Think of us as the kid in the back of a car asking "Is it there yet?" on your behalf.
When we receive an event, we immediately store the original transporter event in our system so that in case of confusion/error or any other reason we can always go back and check what we originally received.
flowchart LR
ret(Retailer)
sk(Skrym)
tr(Transporter)
tr -- Webhook --> sk
sk -. Polling .-> tr
sk -- Webhook --> ret
This is particularly important as many transporters delete event data for shipments older than 6 months.
Skrym provides a set of default event types that we use to categorize the events we receive. These are:
Skrym Event
Description
arrival
The shipment has arrived at a checkpoint
delay
The shipment is delayed
error
An error has occurred with the shipment
delivered
The shipment has been delivered
notification
A notification has been sent to the recipient
departure
The shipment has left a checkpoint
Skrym maps the transporter's event to one of these types. This is done to ensure that we can provide a consistent experience across all transporters.
Events determine Shipment Status
Each shipment has a status. Some events make the status change, while some other does not. A status can be one of four values:
OK
DELAY
PROBLEM
DONE
ARCHIVED
When Skrym receives a transporter event that indicates an error, the shipment's status tends to be changed to
PROBLEM
Notifications events, such as when a text reminder has been sent to the recipient, will never lead to a change in status
The struct for a skrym event is defined by a few fields.
Some data about when the event was created and what the event is tracking (e.g what shipment it is about). It also contains some data regarding what the event means. That data we store in the field EventAspect.
Event Aspect
An event aspect contains information needed to understand what the event "means". This includes data points such as
direction, location and event type.
Field
Usage
Type
A pre-defined type of event (e.g arrival, delay, error, delivered)
Checkpoint*
A abstract place from which the event has occurred, a terminal or maybe while in transit
Message*
If the event contains any specific information to clarify how/when/why/what the event is/means
Next*
The same structure as the checkpoint, but used to say if the event can predict the next "place" we should expect the shipment to arrive at
Direction*
This field is to tell us if the direction of the shipment has changed, maybe the event is a notification of cancellation so that the order has to return
* - optional field'
Checkpoint
Checkpoint and Next are two fields in the event aspect. We use these to indicate what type of place the event has happened at, and what we expect the next event to be (next).
If we get enough information to also know where the Location is, we store a reference to this location so we can accurately recreate the physical journey of a shipment.
