Zone and port subscription examples

Five subscriptions and the calls that read their events back. Each one narrows the same flat filter object in a different direction.

Zone and port IDs are UUIDs you look up first. See Zone & Port Search to look up IDs.

Watch a port for arrivals and departures

The simplest useful subscription: one area, two movement events, delivered by webhook.

With no vessels key this fires for every vessel, which is what you want for a terminal or a berth. We carry custom_reference through untouched, so it is the cheapest way to tie events back to a record in your own system.

Narrow it to flags of concern

Same area, but only vessels flagged to particular states.

"filters": {
  "event_types": ["PORT_ARRIVAL"],
  "zones_ports": ["5e98acb5-4b8a-451b-9280-ddd63d55f8c9"],
  "flag_codes": { "incl": ["ZMB", "MUS"], "excl": [] }
}

flag_codes is an object with incl and excl, not a bare array. You can use both directions at once: include a set of flags and exclude a subset of it, and we apply the exclusion to whatever the inclusion left.

Arriving is two events, not one

PORT_ARRIVAL fires when a vessel has stopped inside the port area, and PORT_AREA_ARRIVAL when it first enters that area. Subscribe to only the first and you hear about calls that happened. Subscribe to both and you get an earlier warning, at the cost of events for vessels that pass through without stopping.

Watch specific vessels in specific places

Combining vessels and zones_ports answers "tell me when any of these ships triggers one of these events in any of these areas", which is a narrower question than either list alone.

"filters": {
  "event_types": ["ZONE_ENTRY"],
  "zones_ports": [
    "5e98acb5-4b8a-451b-9280-ddd63d55f8c9",
    "1c60546c-da9d-425c-8eed-0142af219601"
  ],
  "vessels": ["9074729"]
}

The keys narrow in combination, so this fires only for that IMO and only in those two areas. Drop vessels and it covers every ship in those areas; drop zones_ports and it follows that vessel everywhere.

Add screening, and only hear about what matters

For a busy terminal, every arrival is too many events. Screening cuts the volume down to the ones worth a look.

"settings": {
  "notification_callback_url": "https://webhooks.example.com/compliance",
  "vessel_screening": {
    "active": true,
    "severity_filter": ["HIGH"]
  },
  "filters": {
    "event_types": ["PORT_ARRIVAL"],
    "zones_ports": ["5e98acb5-4b8a-451b-9280-ddd63d55f8c9"]
  }
}

Notifications now carry screening information about the triggering vessel, and severity_filter decides which severities generate a notification at all.

Add a daily digest alongside the webhook

"email_settings": {
  "email_enabled": true,
  "scheduler": { "schedule_type": 1, "at_time": "08:00" },
  "additional_recipients": ["port.ops@example.com"]
}

The example's schedule_type of 1 sends one digest a day. 0 sends each notification as it is generated, and every other value is the number of digests you get a day:

`schedule_type`	Delivery
`0`	Immediate, one email per notification
`1`	One digest a day
`2`	Two digests a day
`3`	Three digests a day
`4`	Four digests a day
`24`	One digest an hour

These are the only values. at_time is the UTC time, as HH:mm, at which the first digest goes out, and schedule_type sets how many further digests follow that day, spaced evenly across it.

Everything generated in the window arrives in the email body with a CSV of the event details attached.

Check two things before relying on the digest

A mail gateway will often strip the CSV attachment, so confirm your organisation allows CSV and ZIP through to the receiving mailbox. Every address in additional_recipients also needs its own Pole Star account; an arbitrary distribution list will not receive it.

Read the events back

For one subscription over a window:

Across every subscription at once:

For a named set of subscriptions, POST the list instead. That is why a read operation is a POST, and it is the right call when you have more subscription IDs than will sit comfortably in a query string:

timestamp_start is required on all three. includeTotal adds the total matching count, which costs a count query, so leave it off when you are paging through and only need the next page.

Pause without losing the configuration

PUT replaces and does not merge, so send the whole settings object. A subscription paused this way keeps its filters, and you can switch it back on unchanged.

Zone & Port Notifications

The filter model, screening and the three delivery routes.

Vessel Notifications: Worked Examples

The ship-shaped counterpart, with a different filter shape.

Notifications & Webhooks

Receiving endpoint requirements and delivery behaviour.

Zone & Port Notifications: Worked Examples

Watch a port for arrivals and departures#

Narrow it to flags of concern#

Watch specific vessels in specific places#

Add screening, and only hear about what matters#

Add a daily digest alongside the webhook#

Read the events back#

Pause without losing the configuration#

Related#