How-to
Alerts, alert areas and webhooks: a practical guide
Alerts turn the map from something you check into something that tells you. This guide sets up three useful ones step by step, lists the exact condition behind every alert type, and is straightforward about how quickly each kind of notification actually reaches you.
Last reviewed
How alerts work
There are two ways to ask for an alert, and they watch different things.
- A rule on a vessel. You add a ship to your fleet and switch on rules for it: arrival, departure, a change of destination, and so on. Each rule compares the vessel’s newest AIS report with its previous one and fires when the condition is met.
- An alert area. You draw a rectangle on the map. An alert is raised when a vessel crosses its edge. An area can watch just your fleet, or every vessel of the ship types you pick.
Both are part of Pro (USD 17 a month). A free account can keep a fleet of up to 10 vessels and see them on the map, but cannot set alerts. Pro allows 500 vessels, 20 alert areas and 5 webhook endpoints.
Alerts are produced as position reports are processed, so an alert is recorded within a minute or so of the report that caused it reaching us. When it reaches you depends on how you choose to receive it — see delivery below before you build anything that depends on speed.
Example: tell me when my vessel arrives
- Find the ship with the search box on the map — by name, IMO number or MMSI — and open it.
- In the vessel panel choose Add to fleet, then Alerts.
- Switch on Arrival, and Departure if you want to know when she sails again, then choose Save alert rules.
You can do the same for many vessels at once from your fleet page, which also takes a pasted list of IMO numbers or MMSIs.
For a vessel that matters, add a second net that does not depend on the crew: draw an alert area around the port or its anchorage, set it to My fleet only, and let it tell you when the ship crosses the line. The two alerts together also tell you something neither does alone — how long she waited outside.
Example: tell me when any tanker enters this area
- On the map, open Layers and choose New alert area.
- Drag a box over the water you want watched — a terminal approach, a strait, an anchorage.
- Give it a name you will recognise in an inbox, such as “Terminal approach”.
- Under Alert me about choose Any vessel, then under Ship types select Tanker.
- Leave Enters the area on. Switch on Leaves the area as well if you want both ends of each visit.
Areas are managed afterwards under Fleet → Areas. A few things to know:
- “Tanker” means AIS ship-type codes 80–89, as programmed into each ship’s transponder. A tanker broadcasting the wrong type is not matched. See AIS ship types explained.
- Only crossings we witness count. Drawing an area around ships that are already inside raises nothing, and neither does a vessel first heard when it is already inside. We alert on a ship seen outside and then seen inside.
- The edge has a little tolerance. A vessel anchored right on the boundary, or drifting across it with the tide, does not generate a stream of enter and leave alerts.
- Big, busy areas are limited. An area that watches any vessel can be at most 60° of longitude wide and 40° of latitude tall, and a single area stops raising alerts once it has produced a large number within an hour. If you hit that, the area is too broad to read anyway: narrow the box or the ship types.
Example: tell me when a vessel goes quiet
The AIS signal lost rule fires when no position has been received from a vessel for a period you choose — from 15 minutes to 24 hours, 30 minutes unless you change it. It is set in the same place as the arrival alert.
Be clear about what it measures. It means we have stopped hearing the ship, which happens when:
- the ship has sailed out of range of shore receivers — by far the most common reason;
- the transponder has been switched off or has failed;
- a receiver near the ship has gone down.
On a coastal passage or in port, where reception is continuous, a gap is worth a look. For a ship heading out across an ocean it will fire every time she leaves the coast, and tells you only that. Choose a longer period for vessels on routes with patchy coverage, and combine it with a departure alert so you know which kind of silence you are looking at.
The rule is careful in one respect: silence is only counted while our own data feed is running. If our feed drops, you are not sent a “signal lost” alert for every ship in your fleet.
Every alert rule, exactly
These are all the alerts VesselTrack can raise. The wording is the same as in the product.
- ArrivalVoyage
- The vessel reports it has moored or anchored.
- DepartureVoyage
- The vessel gets under way after being moored or at anchor.
- Destination changeVoyage
- The crew enters a new destination in the AIS transponder.
- Navigation status changeMovement
- Any change of reported status, e.g. under way → restricted manoeuvrability.
- Speed changeMovement
- Speed over ground changes by 2 knots or more between reports.
- Speed thresholdMovement
- Speed crosses the threshold you set, in either direction.You set the value: 0.5–60 kn.
- Course alterationMovement
- Heading changes by at least the number of degrees you set.Adjustable: 5–180°, default 45°.
- AIS signal lostSignal
- No position report has been received for the period you set.Adjustable: 15–1,440 min, default 30 min.
- Name changeIdentity
- The vessel starts broadcasting a different name.
- Ship type changeIdentity
- The broadcast ship-type code changes.
- Entered areaAreas
- A matching vessel crosses into one of your alert areas.
- Left areaAreas
- A matching vessel leaves one of your alert areas.
Three details apply to all of the per-vessel rules:
- Missing values never fire. AIS has “not available” values for speed, heading and status. A report carrying one is ignored by the rule concerned rather than treated as a change.
- Each change fires once. A rule reacts to the moment a value changes, not to every report while it stays changed.
- Identity and voyage rules follow the slower message. Name, ship type and destination are broadcast every six minutes, not every few seconds, so those alerts trail the change by up to that long.
Delivery: inbox, email and webhooks
An alert is recorded once and can reach you three ways. They are not equally fast.
| Channel | When it reaches you |
|---|---|
| Alert inbox | As soon as the alert is recorded. Open Fleet → Alerts, or watch the unread count on the Fleet button on the map. Alerts stay in the inbox for 90 days. |
| Every 10 minutes: one message listing the alerts not yet emailed to you. It is a digest, not an instant notification, and you get at most one email an hour: alerts raised sooner than that after an email are sent together in the next one. Alerts more than 7 days old are never emailed. Turn the digest on or off, and choose which alert types it includes, under Account → Alerts. | |
| Webhook | Deliveries are sent by a scheduled job that runs about once a minute. Events more than 72 hours old when it runs are not sent. Set up under Account → Webhooks. |
Those schedules are read from the same configuration that runs the jobs, so this page changes when they do. If you need to know within minutes, use the inbox or a webhook; email is a digest. While the live AIS feed is down no new alerts are raised, and both jobs run less often — at least every 6 hours — so a queued webhook retry can wait up to that long.
Webhooks in a little more detail
A webhook is an HTTPS address of your own that we send a small JSON message to, so that your software can act on an event without anyone reading an email. An endpoint is one of two kinds:
- My alerts — everything that lands in your alert inbox, from vessel rules and alert areas alike.
- All vessels, filtered — events from every vessel we receive, narrowed by ship category, flag, destination, a bounding box or specific vessels. This kind has its own events, including
port.arrival,port.departureandport.expected_arrival, which are based on position rather than on the crew’s status.
What your receiver needs to handle:
- Every request carries an
X-VesselTrack-Signatureheader, an HMAC-SHA256 of the body made with a secret shown once when you create the endpoint. Verify it, and reject anything that fails. - Answer with a 2xx status within 8 seconds. A failed delivery is retried up to 5 more times with growing gaps; after 10 deliveries in a row have failed completely, the endpoint is switched off and you are emailed.
- Delivery is at-least-once and not in order. Use the delivery id to drop duplicates and the event time to put things in sequence.
- An endpoint receives at most 500 deliveries an hour. Events beyond that are dropped, not saved for later.
The message format, a signature-verification example and the full event list are in the API reference.
What alerts cannot do
- They cannot see what the receivers cannot hear. Our data is terrestrial AIS. A vessel beyond receiver range raises no alerts until it is heard again, and then only for what changes from that point. An arrival at a port with no receiver nearby goes unnoticed.
- They stop when our feed stops. If no position has reached us for 30 minutes the site reports the feed as offline. No alerts are produced during an outage and none are created afterwards for what was missed.
- They inherit AIS’s weaknesses. A wrong status, a stale destination or a mistyped ship type produces wrong alerts or none. How AIS ship tracking works explains where each comes from.
- They are not a safety system. Do not rely on a VesselTrack alert for navigation, security or anything where a missed notification would cause harm.
The practical advice is the same as for the map: look at the coverage for the places you care about before you depend on it. The map, search, vessel pages and port pages are free for exactly that purpose.
Sources
Statements about AIS and maritime standards on this page were checked against the following. Statements about what VesselTrack does describe the software as it runs today.
- US Coast Guard Navigation Center — Class A AIS position report and static/voyage dataField-by-field contents of AIS messages 1, 2, 3 and 5, reproduced from Recommendation ITU-R M.1371-5: navigational status codes, ship-type codes, “not available” values.
- US Coast Guard Navigation Center — Shipborne AIS class comparison (PDF)Transmit power and position-reporting intervals for Class A, Class B-SO and Class B-CS.
Found a mistake? Email support@vesseltrack.net or see how to contact us. Corrections are made on this page and the review date is updated.