REAL-TIME MARITIME EVENT ALERTS

Vessel Notifications API

Subscribe to real-time vessel events and get instant notifications via webhooks or WebSocket. Port arrivals, departures, ETA changes, destination updates, speed changes, and geofence alerts for 682,000+ vessels.

Start Free View Documentation

Event Types

682K+

Vessels Available

Delivery Channels

<1 min

Event Latency

What the Notifications API Provides

Subscribe to vessel events and receive instant alerts through webhooks or WebSocket. No polling required — events are pushed to you as they happen.

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 change speed beyond a threshold or update their navigational status (anchored, moored, underway, etc.).

Geofence Events

Define geographic boundaries and get alerts when vessels enter or exit your custom geofence zones.

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"
  }'

TypeScript

import { VesselAPI } from "vesselapi";

const client = new VesselAPI({ apiKey: "YOUR_API_KEY" });

// Create a notification for ETA changes on specific vessels
const notification = await client.notifications.create({
  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",
});

console.log(`Notification created: ${notification.id}`);

// List all active notifications
const notifications = await client.notifications.list();
for (const n of notifications.data) {
  console.log(`${n.name} - ${n.eventTypes.join(", ")}`);
}

Python

from vesselapi import VesselClient

client = VesselClient(api_key="YOUR_API_KEY")

# Create a geofence notification for the Suez Canal
notification = client.notifications.create(
    name="Suez Canal Monitor",
    event_types=["position.geofence_enter", "position.geofence_exit"],
    geofence={
        "latTop": 31.3,
        "latBottom": 29.9,
        "lonLeft": 32.3,
        "lonRight": 32.4,
    },
    webhook_url="https://your-app.com/webhooks/geofence",
    webhook_secret="your_signing_secret",
)

print(f"Notification created: {notification.id}")

# Test the notification to verify delivery
client.notifications.test(notification.id)

Webhook Payload Example

{
  "object": "event",
  "event": {
    "id": "evt_550e8400-e29b-41d4-a716-446655440000",
    "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-Vessel-Signature header with an HMAC-SHA256 signature. 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`	Generic — fires on every AIS position report, even if the vessel hasn't moved. Ideal for heartbeat monitoring.	Position
`position.position_changed`	Specific — fires only when the vessel's actual geographic coordinates change. Filters out stationary reports.	Position
`position.speed_changed`	Speed changed beyond configured threshold	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

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. Supports cursor-based pagination and filtering by status.

GET /v1/notifications/{id}

Get details of a single notification subscription, including delivery history and error counts.

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 delivery status and response code.

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 typically delivered within one minute of detection. AIS data is ingested continuously from terrestrial receivers, and events are generated and dispatched as soon as state changes are detected. WebSocket delivery is near-instantaneous once the event is generated.

What happens if my webhook endpoint is down?

Failed webhook deliveries are retried automatically with exponential backoff. Retries occur at 30 seconds, 5 minutes, 30 minutes, 2 hours, and 24 hours after the initial attempt. If all retries fail, the event is logged and the notification is flagged with an error status.

How do I verify webhook signatures?

Each webhook delivery includes an X-Vessel-Signature header containing 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. You can specify a list of vessel IDs (MMSI or IMO) to monitor specific vessels, or omit the vessel filter to receive events for all vessels. Geofence-based notifications trigger for any vessel entering or exiting the defined area regardless of vessel filters.

Is there a free tier for the notifications API?

Yes. VesselAPI offers a free tier that includes access to the notifications endpoints. Sign up to get your API key and start creating notification subscriptions immediately. Paid plans offer higher event limits and additional delivery guarantees.

Start Receiving Vessel Events Today

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

Get Free API Key View Pricing