Webhook events
A Safecube webhook endpoint receives only the event types it subscribes to, set in the filterTypes field of the endpoint. Events fall into two groups: operational events, which follow the lifecycle of a whole shipment, and alerts raised on specific container and vessel milestones. The Svix event catalog of Safecube gives the schema and an example payload of each event.
Operational events
Operational events are enough on their own to use the Webhooks API as a push API. Each one is sent once per shipment, not once per container, and its payload contains the information of the whole shipment.
| Event type | Trigger | Sending |
|---|---|---|
shipment.added.to.endpoint | Safecube received the first tracking data for the shipment. | Sent once, shortly after the shipment is added. |
shipment.in.error | Safecube received no data for the shipment, and the shipment was added more than 24 hours ago. | Sent once per shipment, shortly after the shipment is added. The payload contains the error detected. |
shipment.any.change | One or several events of the shipment changed since the last update. | Sent once for all the containers of the shipment, every time a change is detected. |
shipment.auto.removed | The shipment was removed automatically from the tracked shipments: it was delivered more than 7 days ago, or a new voyage started with the same container. | Sent once, at the removal. The payload contains the reason for the removal. |
shipment.refresh.status.change | The ability of Safecube to refresh the shipment data changed: the latest refresh status, such as OK, under maintenance or no credits left, differs from the previous one. | Sent once for all the containers of the shipment, and not again until the refresh status changes again. The payload contains the current and previous refresh statuses. |
shipment.warning.split_bl | The bill of lading may be split: within the same bill of lading, the events differ from one container to another. | Sent once for all the containers of the shipment, and not again unless the events converge and then diverge again. |
The Adding shipments page explains how to react to shipment.added.to.endpoint and shipment.in.error, and the Auto-removal policy page details when a shipment is removed automatically.
Alerts on actual events
These alerts are sent when the event becomes actual: its isActual field moves to true. The status and event codes are those of the Container Tracking API, listed on the Status and event codes page.
| Event type | Status | Event code | Location type |
|---|---|---|---|
container.arrival.at.pre.pol | — | ARRI | pre-POL |
container.departure.from.pre.pol | — | DEPA | pre-POL |
container.loaded.at.pre.pol | — | LOAD | pre-POL |
container.arrival.at.first.pol | CGI | GTIN | POL |
container.loaded.at.first.pol | CLL | LOAD | POL |
vessel.departure.from.first.pol | VDL | DEPA | POL |
vessel.arrival.at.transhipment_port | VAT | ARRI | transhipment |
container.discharge.at.transhipment_port | CDT | DISC | transhipment |
container.loaded.at.transhipment_port | CLT | LOAD | transhipment |
vessel.departure.from.transhipment_port | VDT | DEPA | transhipment |
vessel.arrival.at.final.pod | VAD | ARRI | POD |
container.discharge.at.final.pod | CDD | DISC | POD |
container.departure.from.final.pod | CGO | GTOT | POD |
container.arrival.at.post.pod | — | ARRI | post-POD |
container.discharge.at.post.pod | — | DISC | post-POD |
container.departure.from.post.pod | — | DEPA | post-POD |
Alerts on date changes
These alerts are sent when the date of the event changes by more than 24 hours, earlier or later, since the previous alert sent for it.
| Event type | Status | Event code | Location type |
|---|---|---|---|
date.changed.container.arrival.at.pre.pol | — | ARRI | pre-POL |
date.changed.container.departure.from.pre.pol | — | DEPA | pre-POL |
date.changed.container.loaded.at.pre.pol | — | LOAD | pre-POL |
date.changed.container.arrival.at.first.pol | CGI | GTIN | POL |
date.changed.container.loaded.at.first.pol | CLL | LOAD | POL |
date.changed.vessel.departure.from.first.pol | VDL | DEPA | POL |
date.changed.vessel.arrival.at.transhipment_port | VAT | ARRI | transhipment |
date.changed.container.discharge.at.transhipment_port | CDT | DISC | transhipment |
date.changed.container.loaded.at.transhipment_port | CLT | LOAD | transhipment |
date.changed.vessel.departure.from.transhipment_port | VDT | DEPA | transhipment |
date.changed.vessel.arrival.at.final.pod | VAD | ARRI | POD |
date.changed.container.discharge.at.final.pod | CDD | DISC | POD |
date.changed.container.departure.from.final.pod | CGO | GTOT | POD |
date.changed.container.arrival.at.post.pod | — | ARRI | post-POD |
date.changed.container.discharge.at.post.pod | — | DISC | post-POD |
date.changed.container.departure.from.post.pod | — | DEPA | post-POD |
New event alert
container.new.event.detected is sent when a new event is detected for a container. A single event is defined by the combination of its status, its event code and the UN/LOCODE of its location (location.unlocode).