Webhooks

Real-time event notifications via HTTP POST — vessel position updates, port arrivals, regulatory changes, NAVAREA warnings and fleet alerts delivered to your endpoint.

Event Types

9 event types

Delivery Latency

< 5 seconds

Retry Policy

5 retries

Signature

HMAC-SHA256

Example Payload — vessel.position_update

// POST https://yourapp.com/webhooks/heymariner

{

"event": "vessel.position_update",

"timestamp": "2026-06-17T04:22:11Z",

"data": {

"imo": "9234194",

"mmsi": "371614000",

"lat": 51.9124,

"lon": 1.3842,

"speed": 14.2,

"course": 078

}

Register Endpoint

POST your HTTPS endpoint URL to /v1/webhooks — receives all subscribed events.

Subscribe to Events

Choose event types and optional filters (vessel IMOs, port UNLOCODE, NAVAREA region).

Verify Signature

Each delivery includes an HMAC-SHA256 signature header. Verify before processing.

Respond with 200

Return HTTP 200 within 10 seconds. HeyMariner retries up to 5 times with exponential backoff.

Webhook Events

vessel.position_update

Vessel AIS position changes beyond threshold

{ imo, mmsi, lat, lon, speed, course, timestamp }

vessel.port_arrival

Vessel enters port ETA window or arrival confirmed

{ imo, port_unlocode, eta, arrival_type }

vessel.port_departure

Vessel departs from port (AIS signal, ATD)

{ imo, port_unlocode, atd, destination }

vessel.status_change

AIS navigational status changes (underway/anchored/moored)

{ imo, old_status, new_status, position }

vessel.dark_event

Watched vessel AIS signal lost for defined period

{ imo, last_seen, last_position, dark_duration }

port.arrival_expected

New ETA filed for vessel at subscribed port

{ imo, port_unlocode, eta, voyage_number }

regulation.update

IMO circular, MSC resolution or regulation amendment published

{ regulation, reference, effective_date, summary }

navarea.warning_new

New NAVTEX or NAVAREA warning issued in subscribed area

{ navarea, subject, broadcast_time, text }

fleet.alert

Fleet-level alert: certificate expiry, PSC detention, incident report

{ imo, alert_type, severity, details }

Signature Verification

// Node.js verification example

const sig = req.headers['x-heymariner-signature'];

const computed = crypto.createHmac('sha256', webhookSecret)

.update(req.body).digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(computed))) {

return res.status(401).json({ error: 'Invalid signature' });

}

REST API Reference MCP Server