Skip to content
Documentation sections

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 typeTriggerSending
shipment.added.to.endpointSafecube received the first tracking data for the shipment.Sent once, shortly after the shipment is added.
shipment.in.errorSafecube 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.changeOne 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.removedThe 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.changeThe 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_blThe 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 typeStatusEvent codeLocation type
container.arrival.at.pre.pol—ARRIpre-POL
container.departure.from.pre.pol—DEPApre-POL
container.loaded.at.pre.pol—LOADpre-POL
container.arrival.at.first.polCGIGTINPOL
container.loaded.at.first.polCLLLOADPOL
vessel.departure.from.first.polVDLDEPAPOL
vessel.arrival.at.transhipment_portVATARRItranshipment
container.discharge.at.transhipment_portCDTDISCtranshipment
container.loaded.at.transhipment_portCLTLOADtranshipment
vessel.departure.from.transhipment_portVDTDEPAtranshipment
vessel.arrival.at.final.podVADARRIPOD
container.discharge.at.final.podCDDDISCPOD
container.departure.from.final.podCGOGTOTPOD
container.arrival.at.post.pod—ARRIpost-POD
container.discharge.at.post.pod—DISCpost-POD
container.departure.from.post.pod—DEPApost-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 typeStatusEvent codeLocation type
date.changed.container.arrival.at.pre.pol—ARRIpre-POL
date.changed.container.departure.from.pre.pol—DEPApre-POL
date.changed.container.loaded.at.pre.pol—LOADpre-POL
date.changed.container.arrival.at.first.polCGIGTINPOL
date.changed.container.loaded.at.first.polCLLLOADPOL
date.changed.vessel.departure.from.first.polVDLDEPAPOL
date.changed.vessel.arrival.at.transhipment_portVATARRItranshipment
date.changed.container.discharge.at.transhipment_portCDTDISCtranshipment
date.changed.container.loaded.at.transhipment_portCLTLOADtranshipment
date.changed.vessel.departure.from.transhipment_portVDTDEPAtranshipment
date.changed.vessel.arrival.at.final.podVADARRIPOD
date.changed.container.discharge.at.final.podCDDDISCPOD
date.changed.container.departure.from.final.podCGOGTOTPOD
date.changed.container.arrival.at.post.pod—ARRIpost-POD
date.changed.container.discharge.at.post.pod—DISCpost-POD
date.changed.container.departure.from.post.pod—DEPApost-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).