REAL-TIME MARITIME EVENT ALERTS

Vessel Notifications API

Subscribe to vessel events and receive push notifications via webhooks or WebSocket. Port arrivals, departures, ETA changes, destination updates, speed changes, and geofence alerts for 700,000+ vessels, including polygon geofencing with attribute filters on the Pro plan.

Start Free View Documentation

Event Types

700K+

Vessels Available

Delivery Channels

5,000

Points per Geofence Polygon

What the Notifications API Provides

Subscribe to vessel events and receive alerts through webhooks or WebSocket. No polling required: events are pushed to you as soon as they are detected.

Port Event Alerts

Get notified when vessels arrive at or depart from ports worldwide. Includes port name, UNLOCODE, and timestamp for each event.

ETA & Destination Changes

Track changes to vessel ETA, destination, and draught. Receive alerts when crew updates the voyage plan via AIS.

Speed & Status Monitoring

Alerts when vessels start or stop moving (configurable speed threshold) or update their navigational status (anchored, moored, underway, etc.).

Polygon Geofencing

Get alerts when vessels enter or exit your zones: a simple bounding box on every paid plan, or polygons with up to 5,000 points and attribute filters (vessel type, subtype, length, ENI) matching any vessel in the area on Pro.

Webhook Delivery

HTTP POST to your endpoint with HMAC-SHA256 signature verification. Automatic retries with exponential backoff on failure.

WebSocket Streaming

Real-time streaming connection for low-latency event delivery. Persistent connection with automatic reconnection support.

Who Uses Vessel Notification APIs

Supply Chain

Track vessel arrivals at destination ports for cargo planning. Get notified when ships enter port areas so logistics teams can prepare for unloading and last-mile delivery.

Fleet Management

Monitor fleet-wide status changes and route deviations in real time. Detect unexpected stops, speed changes, or off-route vessels without manual monitoring.

Port Operations

Automate workflows triggered by vessel arrivals and departures. Schedule berth allocation, pilot dispatch, and resource planning based on real-time port events.

Compliance

Alert on geofence breaches for sanctions zones, environmental protection areas, or restricted waters. Maintain audit trails of vessel movements through regulated regions.

Create a Notification in Seconds

Subscribe to vessel events with a single API call. Choose webhook or WebSocket delivery.

cURL

# Create a webhook notification for port arrival events
curl -X POST "https://api.vesselapi.com/v1/notifications" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Port Arrival Alert",
    "eventTypes": ["port.arrival", "port.departure"],
    "imos": [9321483],
    "webhookUrl": "https://your-app.com/webhooks/vessel-events",
    "webhookSecret": "your_signing_secret"
  }'

JavaScript

// Create a notification for ETA changes on specific vessels
const res = await fetch("https://api.vesselapi.com/v1/notifications", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "ETA Change Monitor",
    eventTypes: ["eta.eta_changed", "eta.destination_changed"],
    mmsis: [211331640, 235009757],
    webhookUrl: "https://your-app.com/webhooks/vessel-events",
    webhookSecret: "your_signing_secret",
  }),
});

const { notification } = await res.json();
console.log(`Notification created: ${notification.id}`);

Python (advanced polygon geofence, Pro plan)

import requests, time

BASE = "https://api.vesselapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_PRO_API_KEY"}

# Create a polygon geofence around the Suez Canal matching any vessel
resp = requests.post(f"{BASE}/notifications/advanced", headers=HEADERS, json={
    "name": "suez_canal_monitor",
    "mode": "any_vessel",
    "polygon": {"coordinates": [
        [32.25, 29.85], [32.65, 29.85], [32.65, 31.35], [32.25, 31.35], [32.25, 29.85],
    ]},
    "eventTypes": ["position.geofence_enter", "position.geofence_exit"],
    "webhookUrl": "https://your-app.com/webhooks/geofence",
    "webhookSecret": "your_signing_secret",
})
resp.raise_for_status()

# Wait for prefill to complete, then the notification is live
while True:
    n = requests.get(f"{BASE}/notifications/advanced/suez_canal_monitor",
                     headers=HEADERS).json()["notification"]
    if n["prefillStatus"] == "ready":
        break
    time.sleep(2)

# Send a test event to verify delivery
requests.post(f"{BASE}/notifications/advanced/suez_canal_monitor/test", headers=HEADERS)

Webhook Payload Example

{
  "object": "event",
  "event": {
    "id": "94ff8b0d-08d8-466c-b37a-c024117b8880",
    "type": "port.arrival",
    "timestamp": "2026-03-27T08:14:32Z",
    "detectedAt": "2026-03-27T08:14:45Z",
    "notificationId": "550e8400-e29b-41d4-a716-446655440001",
    "vessel": {
      "imo": 9321483,
      "mmsi": 477045900,
      "vesselName": "EVER GIVEN"
    },
    "data": {
      "portEvent": {
        "event": "Arrival",
        "timestamp": "2026-03-27T08:14:32Z",
        "vessel": { "imo": 9321483, "mmsi": 477045900, "name": "EVER GIVEN" },
        "port": { "name": "Rotterdam", "unlo_code": "NLRTM", "country": "Netherlands" }
      }
    }
  }
}

Webhook security: All webhook deliveries include an X-Signature-256 header (sha256=<hex>) with an HMAC-SHA256 signature of the request body, plus X-Event-Type and X-Delivery-ID headers for routing and deduplication. Verify the signature using your webhook secret to authenticate requests. See the notification docs for verification examples.

Supported Event Types

Subscribe to any combination of event types. Each notification can listen for one or more of the following events.

Event Type	Description	Category
`port.arrival`	Vessel arrives at a port	Port Events
`port.departure`	Vessel departs from a port	Port Events
`eta.eta_changed`	Crew-reported ETA has shifted beyond the configured threshold	ETA / Voyage
`eta.destination_changed`	Vessel destination has changed	ETA / Voyage
`eta.draught_changed`	Vessel draught has been updated (loading/unloading indicator)	ETA / Voyage
`position.update`	Broad: fires when a new AIS report changed any tracked field (coordinates, speed, course, heading, or nav status). Ideal for continuous tracking.	Position
`position.position_changed`	Specific: fires only when the vessel's actual geographic coordinates change. Filters out stationary reports.	Position
`position.speed_changed`	Speed crossed the stopped/moving boundary (configurable threshold): the vessel started or stopped moving	Position
`position.nav_status_changed`	Navigational status updated (anchored, moored, underway, etc.)	Position
`position.geofence_enter`	Vessel entered a defined geofence zone	Geofence
`position.geofence_exit`	Vessel exited a defined geofence zone	Geofence

Standard notifications support all 11 event types. Advanced polygon notifications emit the geofence events, plus the eta.* family when watching an explicit vessel list. See the compatibility matrix.

Available Endpoints

POST /v1/notifications

Create a new notification subscription. Specify event types, vessel filters, delivery method, and optional geofence.

GET /v1/notifications

List all notification subscriptions for your account.

GET /v1/notifications/{id}

Get the full configuration of a single notification subscription.

PUT /v1/notifications/{id}

Update an existing notification. Change event types, vessel filters, delivery URL, or pause/resume delivery.

DELETE /v1/notifications/{id}

Delete a notification subscription. Stops all event delivery immediately.

POST /v1/notifications/{id}/test

Send a test event to verify your webhook endpoint is configured correctly. Returns per-channel delivery status and response code.

WS /v1/ws?notification_id={id}

WebSocket stream of events for a standard notification, authenticated with the same Bearer key.

POST /v1/notifications/advanced PRO

Create an advanced notification: polygon geofence, attribute filters, any-vessel matching or a list of up to 10,000 vessels. Managed by name via GET/PUT/DELETE /v1/notifications/advanced/{name} plus a /test endpoint.

WS /v1/ws/advanced?name={name} PRO

WebSocket stream of events for an advanced notification.

Explore the full API reference →

Frequently Asked Questions

What is the difference between webhook and WebSocket delivery?

Webhooks deliver events as HTTP POST requests to your endpoint, one event per request. They work well for server-to-server integrations and require no persistent connection. WebSocket provides a persistent streaming connection with lower latency, ideal for real-time dashboards and applications that need immediate updates.

How quickly are events delivered after they occur?

Events are produced by continuously evaluating incoming AIS data: advanced (polygon) notifications are evaluated roughly every 60-90 seconds, standard notifications roughly every 5 minutes. Once an event is generated, webhook and WebSocket delivery are immediate. Every event carries both the original AIS report time and the detection time, so you can measure the lag yourself.

What happens if my webhook endpoint is down?

Failed webhook deliveries are retried up to 3 times with exponential backoff (1, 2, and 4 seconds), with a 10 second timeout per attempt. After all retries are exhausted the event is dropped, so build your receiver to be highly available, and deduplicate on the X-Delivery-ID header, which stays the same across retries.

How do I verify webhook signatures?

Each webhook delivery includes an X-Signature-256 header containing sha256=<hex>, an HMAC-SHA256 hash of the request body signed with the secret you provided when creating the notification. Compute the same hash on your end and compare to authenticate the request.

Can I subscribe to events for all vessels or just specific ones?

Both. Standard notifications watch an explicit list of up to 100 vessels by IMO or MMSI. For area-wide monitoring without naming vessels, advanced notifications (Pro plan) match any vessel inside a polygon, optionally narrowed by attribute filters such as vessel type or ENI presence.

Which plans include the notifications API?

Standard notifications are included in every paid plan: Basic (3 active notifications), Starter (5), Growth (10), and Pro (unlimited). Advanced polygon notifications are a Pro feature. The free tier does not include notifications. See pricing.

Start Receiving Vessel Events Today

Get your free API key and create your first notification subscription in minutes.

Get Free API Key View Pricing