Vessel notification subscription examples

You can have every event Voyage Insights returns on request pushed to you as it happens instead. A subscription names the vessels, switches on the event types you care about, and says where to deliver.

Four worked subscriptions follow, from a single-vessel watch to a whole-fleet one, then the lifecycle calls for managing them.

The shape of a subscription

One POST /notifications/v1/vessels creates a subscription. The envelope is small; the work is in settings.filters.

{
  "name": "Panama Canal transit watch",
  "description": "Zone entry and exit alerts for vessels transiting the Panama Canal",
  "custom_reference": "FLEET-OPS-2141",
  "active": true,
  "settings": {
    "imo": "9074729",
    "notification_callback_url": "https://webhooks.example.com/event-notifications",
    "filters": {
      "zones": {
        "active": true,
        "event_types": ["ZONE_ENTRY", "ZONE_EXIT"],
        "zone_types": ["Jurisdictional"],
        "zone_sub_types": ["Internal Waters"]
      }
    }
  }
}

name and settings are the only required fields at the top level, and filters is required inside settings. custom_reference is yours. We carry it through untouched, so it is the cheapest way to tie a subscription back to a record in your own system.

Only switch on the filters you want

Each key inside filters is one event type, and each carries its own active flag. A filter key you leave out is off. You do not need to list every event type with "active": false to disable it, and omitting them keeps the payload readable and makes a later diff meaningful.

Watching one vessel for port calls in sanctioned countries

Monitor a single hull, and only for arrivals in a named set of countries.

{
  "name": "Vessel 9285184: sanctioned country arrivals",
  "custom_reference": "Sanctions monitoring - 9285184",
  "active": true,
  "settings": {
    "imo": "9285184",
    "notification_callback_url": "https://webhooks.example.com/sanctions-alerts",
    "filters": {
      "ports": {
        "active": true,
        "country_codes": ["VEN", "SYR", "IRN", "RUS"],
        "event_types": ["PORT_AREA_ARRIVAL", "PORT_ARRIVAL"]
      }
    }
  }
}

Both arrival events are included deliberately. PORT_AREA_ARRIVAL fires when the vessel enters the port area, and PORT_ARRIVAL when it stops inside it. The first is the early warning; the second confirms it called instead of passing through.

Watching a whole fleet

Swap imo for fleet_id and the same subscription covers every vessel in that fleet.

{
  "name": "Mediterranean fleet: high risk zone entries",
  "active": true,
  "settings": {
    "fleet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "notification_callback_url": "https://webhooks.example.com/high-risk-alerts",
    "email_settings": {
      "email_enabled": true,
      "scheduler": { "schedule_type": 24, "at_time": "09:00" },
      "additional_recipients": ["fleet.manager@example.com"]
    },
    "filters": {
      "zones": {
        "active": true,
        "event_types": ["ZONE_ENTRY"],
        "zone_types": ["IBF"],
        "zone_sub_types": ["HRA", "War Risk Area", "Piracy"]
      }
    }
  }
}

We resolve fleet membership when each event is evaluated, not when the subscription is created. Add a vessel to the fleet and it starts generating notifications; remove it and it stops. Neither requires touching the subscription. Fleets are managed from Domain & Fleet.

Reach for a fleet when the monitoring is identical

A fleet subscription applies one set of filters to every member, so it suits groups of vessels that need the same oversight: a trading fleet, a region, a compliance programme. Vessels that need their own thresholds want their own subscription, and the two approaches coexist on the same account.

Watching a fleet for AIS gaps

{
  "name": "Atlantic fleet: AIS gap alerts",
  "active": true,
  "settings": {
    "fleet_id": "b2c3d4e5-6789-0123-4567-890123456789",
    "notification_callback_url": "https://webhooks.example.com/ais-gaps",
    "filters": {
      "ais_reporting_gaps": {
        "active": true,
        "gap_threshold_gte": 4
      }
    }
  }
}

gap_threshold_gte is in hours, and the same caution applies as on the polled endpoint: short thresholds return noise, because satellite coverage is imperfect and equipment fails.

Ten event types, each its own key inside filters:

Filter key	Fires when
`ports`	A port area, port or berth arrival or departure
`zones`	A zone entry or exit
`ais_reporting_gaps`	The vessel stops transmitting for longer than your threshold
`sts_pairings`	A ship-to-ship pairing is detected
`positional_discrepancies`	Positions stop behaving like a real track
`draught_change`	The reported draught changes
`ais_destination_change`	A new destination is entered in the AIS message
`ais_eta_change`	A new ETA is entered in the AIS message
`mmsi_change`	The MMSI number changes
`navigational_status_change`	The navigational status changes

The last five need only "active": true, since there is nothing to threshold.

How zone filters combine

Most event types accept zone filters, and the logic is the part people get wrong.

An event must match at least one zone_id if you supplied any, and at least one zone_type if you supplied any, and at least one zone_sub_type if you supplied any. Omit a dimension entirely and it stops narrowing.

The subtlety is that an event can be associated with several zones at once, because zones overlap. We evaluate the match across all of an event's zones together, not zone by zone, so an event qualifies if one of its zones satisfies the ID test and a different one satisfies the type test. It does not need a single zone that satisfies every criterion.

Zone IDs come from the search endpoints described on Choosing Zone Endpoints, and the type vocabulary is on Zone & Port Types.

Delivery

Two channels, and they are not exclusive:

Webhook. Set notification_callback_url and we POST each notification to it as it is generated.

Email. Set email_settings.email_enabled to true and choose a scheduler.schedule_type from the table below. additional_recipients adds addresses beyond the subscription owner.

schedule_type decides whether email arrives one at a time or batched. 0 sends each notification as it is generated. Every other value batches notifications into a digest, and the number is how many 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 the remaining digests are spaced evenly across the day according to how many schedule_type specifies.

Notifications & Webhooks covers endpoint requirements, retries and what a delivery looks like on the wire.

Managing a subscription

Listing what you have

GET /notifications/v1/vessels returns your subscriptions, with limit and offset for paging and an active parameter to show only live or only paused ones.

GET /notifications/v1/vessels/{id} returns a single subscription.

Reading the notifications produced

Changing one

Pausing instead of deleting

Notifications & Webhooks

Webhook endpoint requirements, delivery behaviour and email setup.

Voyage Insights

The same events, polled over a time window instead of pushed.

Zone & Port Types

The type and sub-type vocabulary the zone filters expect.

Worked Examples

The shape of a subscription#

Watching one vessel for port calls in sanctioned countries#

Watching a whole fleet#

Watching a fleet for AIS gaps#

What you can subscribe to#

How zone filters combine#

Delivery#

Managing a subscription#

Related#