# Webhook events

> Safecube webhooks send operational shipment events, such as shipment.added.to.endpoint and shipment.any.change, and alerts on specific container and vessel milestones — actual events and date changes of more than 24 hours at the POL, POD, transhipment, pre-POL and post-POD locations.

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](https://www.svix.com/event-types/eu/org_2VwHMERd77Ne7QX11CHCWBUSb1u/) 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](/en/api/webhooks/guides/adding-shipments) page explains how to react to `shipment.added.to.endpoint` and `shipment.in.error`, and the [Auto-removal policy](/en/api/webhooks/guides/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](/en/api/container-tracking/guides/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`).
