DEV Community: VesselAPI

What 'Real-Time' Actually Means for a Vessel Tracking API

VesselAPI — Sun, 21 Jun 2026 14:44:04 +0000

Open any consumer ship-tracking website, zoom in on the Strait of Dover, and you'll see hundreds of little arrowheads gliding across the channel as if you were watching a live camera feed. It feels continuous. It feels like now.

It isn't. Not really. And the gap between what "real-time" feels like and what it actually is turns out to be the most important thing to understand before you start building anything on top of a vessel tracking API.

So let's look at it properly.

The thing you're actually receiving

A ship doesn't broadcast its position to a satellite that beams it instantly into your laptop. It broadcasts an AIS message — a short burst on one of two VHF channels, about 256 bits long, containing its identity, position, course, speed, and heading. AIS stands for Automatic Identification System, and it was designed in the 1990s primarily so that ships could avoid hitting each other, not so that you could draw nice dots on a Mapbox tile.

This origin matters. AIS is a collision-avoidance protocol that the rest of the world has retrofitted into a global tracking network. The clue is in how often a ship transmits: a vessel moving fast and turning sharply sends a position every 2 seconds. A vessel anchored or moored might send one every 3 minutes. The system spends its bandwidth where danger lives, not where dashboards want it.

Those VHF bursts then have to be heard by something. Two somethings, really:

Terrestrial receivers — antennas on coastlines, harbours, and ships, with a range of roughly 40 nautical miles. Coverage is excellent near land, nonexistent in the middle of the Pacific.
Satellites — low-Earth-orbit constellations that pick up AIS signals from open ocean. Coverage is global, but a given patch of ocean might only be overflown every 10 to 90 minutes depending on the constellation. And satellites struggle in busy areas, because hundreds of ships transmitting on the same frequency at the same time produce a sort of radio shouting match.

By the time a position reaches an API, it has been: broadcast by the vessel, received by a terrestrial antenna or a satellite, relayed to a ground station, decoded, deduplicated against other receivers that heard the same burst, and written to a database. The latency budget for that pipeline ranges from a couple of seconds (a tug in Rotterdam harbour) to tens of minutes (a bulk carrier two-thirds of the way across the Indian Ocean).

So when an API says "real-time vessel tracking," what it can honestly promise is: the most recent position we have, with the timestamp of when the vessel actually transmitted it. The honesty lives in that second clause.

The latency budget, written down

Let's make this concrete. Here's a rough decomposition of the lag between a ship being somewhere and your code knowing it:

Reporting interval — 2 seconds to 3 minutes, depending on the vessel's state.
Reception delay — near-zero for terrestrial, anywhere from seconds to an hour for satellite, depending on overflight schedule and message collisions.
Aggregation and ingestion — a few seconds to tens of seconds inside the data provider's pipeline.
Your polling interval — entirely up to you, and usually the biggest contributor to your perceived latency.

Numbers 1 and 2 are physics and orbital mechanics. You cannot beat them. Number 3 is engineering, and a good provider keeps it small. Number 4 is yours to design.

This is why every position you fetch from a vessel API comes with a timestamp — and why that timestamp matters more than the moment you received the response. The data isn't lying when it's 12 minutes old. It's telling you the truth: this is where the ship was 12 minutes ago, and we haven't heard a peep since.

Pulling positions, properly

Let's actually do it. The VesselAPI Python SDK is installed with pip install vessel-api-python, and the client looks like this:

from vessel_api_python import VesselClient

client = VesselClient(api_key="your_key_here")

There are two distinct concepts in the API, and confusing them is the first mistake everyone makes. A vessel is identity: name, IMO, MMSI, type, flag, tonnage. It doesn't move. A position is a snapshot: latitude, longitude, speed, course, and the timestamp of the AIS burst that produced it. These live behind different endpoints.

# Identity — who is this ship?
vessel = client.vessels.get("9811000").vessel
print(vessel.name, vessel.vessel_type, vessel.imo, vessel.mmsi)

# Position — where was it last seen?
pos = client.vessels.position("9811000").vessel_position
print(pos.latitude, pos.longitude, pos.sog, pos.heading, pos.timestamp)

A few things to notice. The ID is positional and defaults to IMO; pass filter_id_type="mmsi" if you want to look up by MMSI instead. The speed field is sog — speed over ground, in knots — not speed. And timestamp is an ISO-8601 string, which means if you want to compute "how stale is this?", you have to parse it first:

from datetime import datetime, timezone

reported = datetime.fromisoformat(pos.timestamp.replace("Z", "+00:00"))
age = datetime.now(timezone.utc) - reported
print(f"Position is {age.total_seconds():.0f} seconds old")

This little calculation is the most honest line of code you'll write all day. Use it. Surface that age in your UI. A dashboard that displays a 47-minute-old position as if it were live is lying to its users; a dashboard that says "last seen 47 minutes ago" is telling them something true and useful.

Tracking many ships at once

Single-vessel polling is fine for, say, tracking your one chartered tanker. But most real applications care about an area — a port approach, a strait, a fishing ground. For that, the API exposes location queries:

# Everything currently in a rectangle around Rotterdam
box = client.location.vessels_bounding_box(
    lat_min=51.85, lat_max=52.05,
    lon_min=3.80,  lon_max=4.55,
)

for v in box.vessels or []:
    print(v.vessel_name, v.mmsi, v.latitude, v.longitude, v.timestamp)

# Or everything within 10 km of a point
near = client.location.vessels_radius(
    latitude=51.92, longitude=4.48, radius=10000,
)

These return the latest known position for each vessel in the area. Each row has its own timestamp, and those timestamps will not be the same. The tug in the inner harbour might be 4 seconds old; the cargo ship anchored offshore might be 6 minutes old. That's not a bug — it's the protocol working as designed.

How often should you actually poll?

People reach for WebSockets and "live" streams because polling feels primitive. But for AIS data, the rhythm of your polling should match the rhythm of the underlying transmissions, not exceed it. There's no benefit to polling a moored ship every second when it only transmits every three minutes — you'll just see the same row, over and over, while burning your rate limit.

A reasonable heuristic:

Harbour and approach traffic (lots of movement, terrestrial coverage): every 10 to 30 seconds.
Coastal traffic at cruising speed: every minute or two.
Open-ocean voyages (satellite-dependent): every 5 to 15 minutes is plenty.

If a position's timestamp hasn't advanced since your last poll, nothing new has happened. The vessel hasn't moved into a new reporting state, or no receiver has heard from it since. Either way, polling harder won't help.

The thing under the thing

So: real-time vessel tracking is not a continuous video stream of the oceans. It is a sparse, opportunistic, physics-bounded sampling of millions of ships, glued together by a global network of antennas and satellites, and exposed to you as the freshest snapshot the system was able to assemble. The word "real-time" is doing some work it can't quite hold up.

But once you see the seams — once you treat that timestamp field as the first-class citizen it is — the whole thing stops feeling like a leaky abstraction and starts feeling like what it is: a remarkable feat of distributed coordination, where a 1990s collision-avoidance radio protocol has been quietly turned into a planetary sensor network.

The ships have been broadcasting all along. Someone just had to listen.

The Email That Arrived Six Hours Late

VesselAPI — Fri, 05 Jun 2026 11:07:45 +0000

You set up the email alert weeks ago. A small, satisfying piece of automation: when the MV Aristos enters the port approach zone, you get a notification. Your team prepares the berth. Customs is warned. The agent is on the way.

The email arrives at 06:14. You read it on the train. You feel briefly organised.

Then you get to the office and find out the Aristos tied up at 04:30.

What happened isn't quite a bug, and it isn't quite a lie. It's the gap between two things that sound almost identical when you read the marketing copy: maritime email alerts and API-based vessel monitoring. They both promise to tell you where your ships are. Only one of them is actually built to.

Six hours is the bad day, to be clear. Most of the time the gap is ten or twenty minutes — long enough to miss the pilot boarding ground, short enough that nobody writes it down. Six hours is what happens when ten or twenty minutes meets a quarantine folder.

The thing about email

Email is, structurally, a notification protocol whose architecture dates to the early 1970s, designed for messages that absolutely do not need to be timely. SMTP itself was formalised in 1982, and it was built to survive a node going down for a week. The entire postal metaphor — inboxes, deliveries, retries — is the wrong shape for "this ship is about to reach the pilot boarding ground."

Here is roughly what happens between an AIS transmission and your inbox. A provider ingests AIS positions from terrestrial receivers and, for open ocean, from satellite constellations. The raw feed itself is fast in some places and slow in others: a Class A transponder on a SOLAS-mandated ship over 300 GT will report every two to ten seconds when underway and every three minutes at anchor; a Class B unit on a smaller coastal trader reports every thirty seconds or so. So already, "real-time AIS" is a range, not a number.

That feed then gets batched, deduplicated, and run through a rule engine on some interior schedule. When a rule fires, a message is queued to SMTP. SMTP hands off to your mail provider, which runs the message through greylisting, spam filters, rate limits, and DMARC checks. Eventually your mail client polls, and the email appears.

It's the stacking that gets you. Each step is harmless on its own. Together they produce a system whose typical latency lives in the minutes and whose worst case lives in the hours, because somewhere in that chain something will occasionally get stuck. Greylisting alone — the spam-prevention trick where unknown senders are politely told to try again later — routinely adds fifteen minutes. A DMARC misalignment can route the alert into a quarantine folder you'll find on Thursday. None of that is the alert provider's fault. It's just what email is: a protocol hardened against spam, not optimised for signalling.

What an API is actually doing

A vessel-tracking API — the kind you'd query from your TMS, your berth-planning tool, or a small internal dashboard — is doing something architecturally different. Instead of pushing a human-readable message through a chain of best-effort hops, it lets your software ask the provider's database a direct question and get a structured answer back.

The most important consequence is that the data is structured. An email says "MV Aristos entered Zone Piraeus-Approach at 04:27." An API response says:

{
  "mmsi": 240958000,
  "imo": 9776418,
  "name": "ARISTOS",
  "lat": 37.9421,
  "lon": 23.6398,
  "sog": 8.4,
  "cog": 287,
  "nav_status": 0,
  "destination": "PIRAEUS",
  "eta": "2024-11-12T04:30:00Z",
  "timestamp": "2024-11-12T04:27:13Z"
}

(Illustrative example — nav_status: 0 is the raw AIS code for "under way using engine"; most APIs normalise it into a string. The MMSI and IMO are fictional.)

You cannot automate against a sentence. You can do almost anything against that JSON: correlate it with your cargo manifest, trigger a berth-allocation algorithm, update a customer-facing ETA, or fire your own email, on your own infrastructure, with your own latency budget.

Latency, the other thing people care about, mostly collapses — with caveats. A REST call typically returns in a few hundred milliseconds. A WebSocket or streaming endpoint can push position updates within a second or two of the provider receiving them. But that's for vessels within range of terrestrial AIS receivers. For open-ocean ships visible only to satellites, the position you fetch in 200 milliseconds may itself be five to twenty minutes old, depending on the constellation's revisit rate. A fast API does not abolish physics; it just stops adding insults on top.

And then there's the part that sounds like a disadvantage and isn't: an API is pull, not push. You decide when to ask. Forty vessels every thirty seconds, if you want — though at that rate you should probably be on a streaming endpoint instead of hammering REST, both for your own sanity and your provider's rate limits. Webhooks sit in the middle: structured push notifications that give you timing control with the data quality of an API call.

The honest version is that polling has its own pains. Your loop has to actually keep running. Authentication tokens have to keep refreshing. You have to detect gaps when the network blips, because unlike email, nothing screams when a request silently never happens. Whoever told you APIs were free of operational debt was selling something.

The honest case for email

If you are a single operator tracking three or four ships, and you don't have a developer, and your workflow is "look at email, walk down the hall, tell someone" — email alerts are fine. They are, in fact, better than fine. No integration, no API keys, no JSON parsing, no rate-limit management. The five-minute delay doesn't matter, because the human in the loop is also operating on minutes-to-hours timescales.

The problem is what happens when that workflow grows. The moment you have more than a handful of vessels, or more than one person needs the data, or the data needs to flow into another system — email becomes a bottleneck disguised as a feature. You end up with people forwarding alerts to each other. You end up with Outlook rules trying to parse vessel names out of subject lines. You end up, eventually, building a brittle script that reads emails and extracts data from them, which is the saddest possible reinvention of an API. If you find yourself writing an email scraper, the universe is trying to tell you something.

The expensive failure mode

The really costly version of this isn't the dramatic six-hour delay. It's the demurrage dispute.

A vessel arrives at 04:30. Your alert lands at 06:14. Weeks later, in a laytime calculation, your records say the ship arrived at 06:14 — that's the timestamp in your system, because that's when the email came in — and the port's records say 04:30. The difference is real money, and the arbitrator has to pick which timestamp to believe. Notice of Readiness disputes turn on exactly this sort of evidentiary gap. The cheap-looking email alert just became the most expensive line item in the quarter.

Around that sit the quieter costs. Berth windows missed by twenty minutes because the arrival alert was queued behind a spam scan. Customer ETAs that were correct in the provider's database but stale in yours, because nobody received the update. An ops team that has slowly developed a learned distrust of its own alerting system, which is the worst failure mode in any monitoring tool. Once people stop trusting the alerts, they start checking manually, and the automation might as well not exist.

None of these look like the alerting broke. They look like ordinary operational friction. That's what makes them hard to attribute and easy to live with.

Email alerts are a notification layer. An API is a data layer. You can build the first on top of the second — many operations teams do exactly that, sending themselves Slack messages or emails generated from API data they control. You cannot build the second on top of the first without writing an email scraper.

The ship doesn't care when the email arrives. It's already alongside.

What a Port Event Actually Is (And Why Your Timestamps Are Lying to You)

VesselAPI — Tue, 02 Jun 2026 10:47:48 +0000

Ask someone when a ship "arrives" at a port and you'll get an answer that sounds obvious. It arrives when it gets there. When it docks. When the cargo comes off. When the captain stops driving.

All of these are different events. And if you're building anything that depends on knowing where ships are and what they're doing — a logistics dashboard, an emissions tracker, a demurrage calculator, a trading signal — the difference between them is the difference between software that works and software that quietly lies to you.

This is a piece about what a port event actually is, why the timestamp on it is more philosophically loaded than it has any right to be, and how to pull clean data out of an API without tripping over the assumptions baked into the question.

The fridge magnet version

Here's the mental model most people start with: ships sail around, and every so often one of them enters a port. The port notices. A row gets written somewhere. That row is a "port event."

That model is wrong. Not approximately wrong — wrong in a way that will burn you the first time you trust it.

In reality, no port "notices" anything. There is no welcome desk at the edge of Singapore harbor. What actually happens is this: commercial vessels of any size that matters — the rule is nominally 300 gross tons on international voyages, 500 GT on domestic ones, plus all passenger ships, but the operational answer is "anything commercially significant" — are required by SOLAS to broadcast their position, speed, heading, and identity. Fishing fleets and pleasure craft are mostly invisible. The protocol is called AIS (Automatic Identification System), broadcasting on two dedicated VHF channels (161.975 and 162.025 MHz) in the maritime band — pure digital TDMA, not voice, distinct from the channels humans actually talk on. Smaller vessels often carry the lighter Class B variant voluntarily.

Coastal stations receive these broadcasts within roughly 40–60 nautical miles of shore; satellites fill in the open ocean, with gaps depending on constellation coverage and how badly signals collide in busy lanes. The aggregate raw stream runs into the hundreds of millions to over a billion messages per day globally — scattered across the planet with no semantic meaning attached. Each message carries an MMSI, a nine-digit identifier that is the actual join key if you ever want to correlate a port event back to the raw position stream.

A "port event" is something a computer infers from that stream. It's a derived fact, not a recorded one.

Inferring a thing that didn't actually happen

To turn position fixes into port events, you need two things: a definition of what a port is in geographic terms, and a rule for when a ship has interacted with it.

The first one sounds easy and isn't. Ports aren't points; they're sprawling, irregular regions that include anchorages outside the breakwater, terminal berths inside it, sometimes a river pilot boarding area many kilometers offshore, and frequently a chunk of open sea where ships wait — sometimes for days, sometimes for weeks — for a berth to free up. Singapore's anchorage zones extend well into the strait. Houston's ship channel runs roughly fifty nautical miles from open water to the inner turning basin, serving a string of independently operated terminals that are colloquially "the port" but legally several different things.

So the first decision is: where does the port end? Serious port-event systems use polygons — hand-drawn or algorithmically refined boundaries, layered: an outer "port limits" polygon, inner anchorage polygons, and individual berth polygons. A vessel crossing one of these boundaries generates a candidate event. The providers who skip the layering and use a single outer polygon are selling you noise — every anchorage stay becomes "arrived," every drift across the line becomes a fresh port call.

The second decision is what counts as a crossing. A naive "is the ship inside the polygon?" check produces nonsense: GPS noise causes vessels at the edge to flicker in and out, generating dozens of fake arrival/departure pairs per hour. Real systems apply hysteresis (you have to be inside for N minutes before it counts) and speed thresholds — a moored ship reports near-zero speed-over-ground, though you have to filter the AIS sentinel codes near 102 knots. The standard reserves 1023 (102.3 knots) for "SOG unavailable" and 1022 (≥102.2 knots) as an overflow marker; both will otherwise inject impossible speeds into your data.

What comes out the other end is a clean event stream: arrival, berth, departure. Each one with a timestamp.

And the timestamps are where it gets interesting.

Why sub-minute matters

Query a well-built port events endpoint for Singapore — say /portevents/port/SGSIN, using the UN/LOCODE — and you should get back events resolved to the second. Not the hour. Not the nearest five minutes. The second.

The demurrage case is the one that matters most, and it gets the least attention. Emissions models get the press; trading signals get the venture money. But the demurrage clock — the meter that charges a charterer for keeping a ship waiting — starts ticking at a contractually defined moment, often tied to Notice of Readiness tendering at the port limits. NOR is a document the master serves, not an AIS event; but AIS-derived port event timestamps are increasingly used as corroborating evidence, and a charterer's lawyer disputing a \$40,000-per-day demurrage claim on a Capesize bulker (an illustrative figure — real rates swing widely with the market) will absolutely cross-reference your data against the NOR timing. If your provider rounded to the nearest hour, you have just introduced uncertainty into someone's evidence. (We learned this the expensive way. Five-minute buckets were fine until they weren't.)

Emissions estimates drift quietly across a fleet when timestamps are coarse, and the trading case is the most fragile of all: watching how fast ships cycle through berths at Port Hedland is, in effect, watching iron ore loading throughput in something close to real time. If your berth timestamp is fuzzy by twenty minutes, your derivative is noise.

The reason the data can be sub-minute is that AIS Class A position reports arrive every 2 to 10 seconds for a vessel underway — strictly, every 10 seconds at port-approach speeds (0–14 knots), every 6 seconds in the 14–23 knot range, every 2 seconds above 23 knots, with course changes collapsing the interval to 2–3 seconds across the board. Class B transponders report every 30 seconds when moving, dropping to 3 minutes when slow; newer Class B+ devices match Class A rates. Stationary vessels at anchor with reported SOG ≤ 3 knots drop to once every 3 minutes — though GPS noise will sometimes keep an anchored ship in the faster-reporting mode anyway, which is one reason boundary flicker is so persistent.

In practice? A lot of providers downsample for storage and the precision dies upstream. If all your timestamps end in :00:00, that's your answer.

Querying it without tripping

The endpoint is GET /portevents/port/{unlocode}. UN/LOCODE is the five-character code maintained by UN/CEFACT — two letters of country code, three characters of location, occasionally including digits (GB2WB is a real one). SGSIN is Singapore. NLRTM is Rotterdam. USNYC is New York; though if you're querying the New York/New Jersey container complex specifically, your provider may use USNWK (Newark) for the New Jersey terminals — the boundary varies by data source, and "the port of New York" turns out not to be one thing. UN/CEFACT publishes updates twice a year, so if you're building something that runs unattended for years, track the changes.

The first thing that'll burn you is that the event types aren't interchangeable. An arrival means the vessel crossed into the port limits — it might still be miles from any berth, anchored, waiting. A berth event means it's actually alongside. A departure means it crossed out again. If you want "time spent loading," you want berth-to-departure, not arrival-to-departure. The difference can be days.

Coverage is uneven. Fishing fleets, very small craft, and naval vessels — which are SOLAS-exempt and may suppress AIS in operational contexts, though plenty of warships and auxiliaries transmit routinely in commercial ports — are inconsistent at best. Query a fishing port and the silence is the answer.

Big ports sometimes contain multiple terminals under one LOCODE, so you might see two berth events for the same call if a vessel shifts berth mid-stay — that's correct behavior, not a bug.

And events arrive out of order. Satellite AIS latency means transmissions from quieter ports can be buffered until the next overhead pass; for busy ports the more common cause of late arrivals is provider ingestion batching. Either way: your code should not assume chronological order, and providers that stamp ingestion time instead of transmission time will quietly destroy your analysis.

The thing under the thing

"A ship arrived at a port" is not an observed fact. It's a model. Somewhere between the radio signal and the JSON, a decision was made about where the port ends and what counts as being inside it. That decision is invisible in the response, and it shapes everything downstream.

The nice thing about port events, compared to most derived data, is that the inference layer is unusually well-defined. The polygons exist. The rules are reproducible. The timestamps, done right, are exact to the second.

You just have to remember that the ship didn't arrive. Something decided it had.

Drawing Lines on the Ocean

VesselAPI — Mon, 25 May 2026 14:48:24 +0000

Imagine you've drawn a circle on a map. It surrounds the Port of Rotterdam, with a bit of slack so you catch ships in the approach. You want to know, in something close to real time, when a particular tanker crosses that line. Not when someone checks a dashboard. Not in a daily report. The moment it happens.

On the face of it, trivial. You have a position. You have a polygon. Check if one is inside the other. Done.

Except almost nothing about that sentence is true in practice.

The thing you think you have

The first lie is "you have a position." You don't, really. You have a position that a vessel's AIS transponder broadcast some number of seconds or minutes ago, that was picked up by a terrestrial receiver (if the vessel is near shore) or a satellite (if it isn't), that was relayed through one or more data networks, that was deduplicated against other reports of the same broadcast, that was timestamped — possibly multiple times, by different systems with slightly different clocks — and that finally arrived in a database.

The position is real. The "now" is negotiable.

Class A transponders — required under SOLAS for commercial vessels of 300 GT and up on international voyages — report as often as every 2 seconds for a vessel above 23 knots or one changing course aggressively, every 6 seconds at 14–23 knots, and every 10 seconds for anything underway below 14 knots regardless of course changes. Anchored or moored, it drops to 3 minutes. (The full ITU-R M.1371 table has more buckets than that; the point is the rate scales with how interesting the vessel currently is.) Class B SO units on smaller craft report every 30 seconds above 2 knots and every 3 minutes at or below — and Class B CS units, increasingly common, just report every 30 seconds and yield the channel to Class A. In a place as busy as Rotterdam, a small vessel's updates can get elbowed out and arrive minutes apart.

Satellite AIS is a separate latency story, and honestly the part of this stack I find most quietly enraging — half the vendors in this space sell "real-time satellite AIS" and quietly mean "ten minutes old, on a good day." The protocol's anti-collision mechanism — Self-Organizing TDMA — assumes each vessel can passively listen to nearby traffic and pick an unoccupied time slot from the local frame map. That assumption holds beautifully at ship-to-ship VHF ranges of roughly 20 nautical miles (the design figure; in practice it varies a lot with antenna height). From orbit, it falls apart: thousands of vessels beyond each other's range have independently claimed the same time slots, and a satellite hears all of them at once. Modern LEO constellations claw a lot of those messages back with wider-bandwidth receivers and probabilistic decoding, but gaps remain. By the time you see the vessel cross the line, the next position might place it 200 meters past it. Or 2 kilometers. The crossing itself is something you have to infer.

Which brings us to the second lie: "check if one is inside the other."

Inside, outside, and the hysteresis problem

Here is what naive geofencing looks like in production: a vessel anchors precisely on the boundary of your polygon. Wind and current shift, and the vessel swings through an arc — a ship on 60 meters of chain in 15 meters of water can sweep through a circle over 100 meters wide, and that's real movement, not noise. On top of that, modern receivers add a few meters of GPS jitter under open sky; multipath in a busy harbor, obstructions, or loss of differential correction can push that to tens of meters regardless of how new the equipment is. Every few minutes, a new position arrives — sometimes just inside the fence, sometimes just outside.

Your webhook fires. And fires. And fires. By morning your downstream system has received 847 "vessel entered port" notifications for the same ship that hasn't actually moved.

This is the same problem thermostats have. The solution is the same too: hysteresis. You don't fire on a single crossing. You fire on a state change that has settled.

Concretely, your handler tracks, for each (vessel, geofence) pair, the last known state — inside, outside, or unknown — and only emits a notification when a new observation contradicts the stored state and you have some confidence the contradiction is real.

The simplest version of "real" is a debounce window. We got this wrong the first time by using a single 60-second window platform-wide. Worked fine for a 5nm port-approach fence. Fired seventeen times per crossing on a harbor entrance fence a pilot boat could cross in twenty seconds. It needs to be per-fence, scaled to the smallest dimension you care about and the fastest legitimate vessel.

A buffer zone — enter when the vessel is 100m inside the boundary, exit when it's 100m outside — works beautifully for circles. For arbitrary polygons it's harder; computing an inward offset of a concave shape is a real piece of geometry, not a one-liner, so most implementations apply the buffer at evaluation time rather than try to redraw the polygon.

Your point-in-polygon test also needs to work in projected coordinates or use a proper spherical distance formula. Raw lat/lon arithmetic produces shapes that are noticeably non-circular at high latitudes — at Rotterdam's 51.9°N, a degree of longitude is about 69 km on the ground, not 111. That's a 38% squash. A "5 nautical mile radius" drawn with naive Euclidean distance is an ellipse, and a visibly wrong one.

There's a subtler trap waiting too. If two position updates for the same vessel arrive within milliseconds — entirely possible with high-frequency feeds and multiple workers — a naive "read state, decide, write state" sequence races against itself. Both workers read outside, both see inside, both fire. In Postgres, the cleanest fix is a conditional update with a timestamp guard: UPDATE ... WHERE state = 'outside' AND last_observed_at < $position_timestamp, then check the affected row count. The timestamp clause matters more than it looks — without it, a satellite position from twenty minutes ago, arriving late after a fresh terrestrial position, will cheerfully roll the state back and re-fire the crossing. (Pessimistic locking with SELECT FOR UPDATE is simpler to reason about; at geofence throughputs the difference rarely matters.)

What the webhook should actually contain

When the notification finally does fire, what goes in the payload matters more than people expect. The receiver may need to argue with it — dismiss it as a stale position, route it to the right downstream system, decide whether to wake someone up. Give them the materials to make that call.

{
  "event": "geofence.entered",
  "event_id": "evt_01HXYZ...",
  "occurred_at": "2024-11-14T08:42:17Z",
  "vessel": {
    "mmsi": 338234567,
    "imo": 9074729,
    "name": "EXAMPLE VESSEL"
  },
  "geofence": {
    "id": "gf_rotterdam_approach",
    "name": "Rotterdam Approach"
  },
  "position": {
    "lat": 51.9461,
    "lon": 4.1234,
    "sog": 8.2,
    "cog": 87,
    "reported_at": "2024-11-14T08:41:55Z",
    "nav_status": "under_way_using_engine"
  },
  "confidence": "high",
  "previous_state": "outside"
}

Ship MMSIs are 9 digits with a Maritime Identification Digit (MID) prefix roughly in the 201–775 range; prefixes starting with 0, 8, or 9 indicate coast stations, group calls, or special devices like AtoN buoys and MOB beacons, not vessels. IMO numbers are 7 digits, last digit a check digit (the 9074729 above validates; we had two bug reports in the first month about an earlier example that didn't, from engineers who pasted it straight into a validator). Use fictional-but-structurally-valid identifiers in your docs.

event_id is the receiver's lifeline. Webhooks get retried. Networks fail. Your handler crashes between sending the HTTP request and committing the "sent" flag. The receiver will see the same event twice, and the only thing that lets them deduplicate cleanly is a stable, unique identifier per logical event — not per delivery attempt. (Their dedup store should be bounded too; storing every event_id forever is an unbounded leak nobody notices until it's six months in.)

occurred_at versus position.reported_at is the gap between when the vessel was where it says, and when your system was confident enough to call the crossing. The vessel was at that lat/lon at 08:41:55. You decided 22 seconds later. That delta is the truth about how much to trust the event.

confidence we argue about more than anything else. Current rule: high when the position is under 5 minutes old and the AIS position-accuracy bit is 1 (indicating <10m, usually DGPS-augmented); low when the last known position is older than 15 minutes or satellite-derived with a long gap; nothing in between. We tried medium and customers ignored it — one of our senior engineers defended it for two sprints on the grounds that "of course there's a middle case" — and the dashboard data was unambiguous: nobody filtered on it, nobody alerted on it, it was decoration. We killed it. Five minutes is generous for a tight fence — a vessel at 20 knots covers over 3 km in that time — so for harbor-scale fences we tighten it. Write the thresholds down. Argue about them in code review, not in incident retros.

nav_status is worth including, but treat it as advisory. It's a 4-bit field that's supposed to reflect operational status, but in practice it's set once at commissioning, or updated via an integrated bridge system that may or may not be wired to anything useful, or just left at the default. Vessels routinely transmit under_way_using_engine while sitting at anchor because nobody changed the setting. Useful for suppression heuristics; dangerous as a hard filter, and frankly this is the AIS field I'd most like to set on fire.

Delivery: the part everyone underestimates

The webhook itself is the easy bit. POST a JSON body to a URL. Twenty lines of code.

What separates a hobby project from production is what happens when the POST fails. And here's the thing nobody tells you up front: your retry schedule is going to be wrong, and you'll only find out which way when something breaks.

Ours used to retry every 10 seconds for 30 minutes. Sounded reasonable. Then a customer — call them Skipper, since they were a logistics shop with a fondness for nautical names — did a 35-minute deploy on a Friday afternoon. By the time their server came back, the queue had drained itself dry against 502s. They missed six hours of arrival notifications across half a fleet, and the angry Slack came in at 2am Saturday because that's when their ops team noticed the discrepancy against the carrier portal. We now use 30s, 2m, 10m, 1h, then hourly for 24h, with ±20% jitter on every interval — without the jitter, when a shared hosting provider recovers from an outage, every retry timer in your system fires at the same millisecond and you DDoS the customer on their way back up. Every retry reuses the same event_id.

Sign the payloads. HMAC-SHA256 of the request body with a per-customer secret, sent in a header — Stripe calls theirs Stripe-Signature, GitHub uses X-Hub-Signature-256. The header name doesn't matter. What matters is that the timestamp goes inside the signed material, and you reject anything more than a few minutes old. Without that, anyone who captures one valid request can replay it forever. Stripe's scheme is the widely-copied reference; copy it shamelessly.

Then there's the delivery log. Every attempt — success, failure, response code, response body, latency — written somewhere queryable. The argument "we never got the notification for vessel X" happens roughly once a month, and the log ends it in thirty seconds: yes you did, here's the 200; or no, we tried six times, your server returned 503 every time.

And two layers of failure handling, which get conflated more often than they should. A consecutive-failure threshold — say, ten failures inside a minute — stops you immediately hammering an endpoint that's clearly down. (Strictly speaking this isn't a full circuit breaker; we don't probe for recovery, we just back off and let the retry schedule do the probing.) A separate endpoint-health policy decides when to give up entirely, mark the endpoint dead, and page someone. We use 24 hours of accumulated failure for that, not 48 — 48 was too forgiving, and customers preferred being woken up to discovering on Monday that nothing had worked since Friday.

The geofence itself is a choice

One last subtlety. A geofence isn't just a shape. It's a modeling decision about what you actually care about.

A circular fence around a port's coordinates is easy to draw and almost always wrong. Ports aren't circles. They have channels, anchorages outside the breakwater, restricted zones inside. A 5-mile radius around Rotterdam's city center will include vessels transiting the North Sea that have nothing to do with the port — and will simultaneously miss the Maas pilot boarding ground, which sits well offshore from the outer terminals. Rotterdam's port complex stretches more than 40 km from the sea inland, so "Rotterdam" as a single coordinate is already a fiction.

A polygon traced along the actual port boundary is better, but vessels at the outer anchorage are arguably already arriving, and a freight forwarder cares about a different boundary than a bunker fuel supplier or a port authority. In practice one vessel crosses several geofences on a single voyage — different fences for different customers asking different questions about the same ship.

Get the infrastructure right and you still have to decide where to put the line. The circle on the map is the easy part.

The 946-Millisecond Tax: Migrating API Key Auth from Bcrypt to HMAC-SHA256

VesselAPI — Sun, 10 May 2026 11:56:03 +0000

I never profiled our authentication middleware. Why would I? It's a key check. The request comes in, you verify the key, you move on. It's plumbing. Then one afternoon I stuck a timer on it and watched it print 946 milliseconds. I re-ran it. Same. Every authenticated request to our API was spending nearly a full second deciding whether the caller was allowed in, before it did a single useful thing.

We were hashing API keys with bcrypt. It felt like the right thing to do. It wasn't.

The 100-Millisecond-Per-Key Tax

When VesselAPI's authentication was first built, someone — by someone I mean me, it was me — did the reasonable thing. User creates an API key, we hash it with bcrypt at cost factor 10 and store the hash. On each incoming request, extract the Bearer token, load the stored hashes from PostgreSQL, and run bcrypt.CompareHashAndPassword against each one until a match is found or the list runs out.

Bcrypt is a password hashing function. It was engineered, on purpose, to be slow. That deliberate slowness is its entire value proposition for passwords: if an attacker steals your database full of password hashes, the CPU cost of bcrypt makes brute-force recovery so expensive it's impractical. At cost factor 10, each comparison takes roughly 65–100 milliseconds depending on hardware. For a user logging into a web app once a day, that's invisible. For every single API call, it's a wall.

Here's what compounded it: bcrypt hashes aren't indexable. The function incorporates a random salt, so the same input produces a different hash each time. You can't compute the hash of an incoming key and look it up in the database — you have to load all the stored hashes and compare them one by one. With 11 active keys in production at the time of our migration, the worst case was 11 bcrypt comparisons. Just under 1.1 seconds of pure CPU work before we even said hello to the request.

11 active keys × ~100ms bcrypt = up to 1.1 seconds of authentication.

The health endpoint with no auth ran in 581ms. Authenticated endpoints ran in 1,466ms. We were paying nearly a second for permission to serve the response.

At the traffic volumes we had, this wasn't causing visible degradation. The load test user was doing 94,315 requests in a month but spread across time. The problem wasn't that the system was falling over — it was that it was architecturally incapable of scaling. With 11 keys to check, bcrypt at cost factor 10 limits you to under one authenticated request per second per core. That's not a "tune this later" ceiling. It's a physics ceiling.

Why bcrypt Is the Wrong Tool for API Keys

We grabbed bcrypt because that's what you use for credentials. We never stopped to ask whether API keys are credentials in the same sense passwords are.

Bcrypt's whole thing is being slow on purpose. If someone steals your password database, the cost of each hash attempt is what stands between them and everyone's plaintext passwords. That makes sense for passwords — people pick terrible ones, reuse them, and there are massive precomputed tables for cracking common choices.

API keys are not that. Ours are 256 bits of cryptographically random noise. You'd need something like 2²⁵⁵ guesses to brute-force one. At a billion attempts per second, that's — let me check — longer than the Sun will exist. So what was bcrypt's cost factor actually buying us? Nothing. The keys were already uncrackable. We were paying 100 milliseconds per request for protection against a threat that doesn't apply.

The real risk with API keys is leakage: someone commits one to a public repo, or it shows up in a log file, or a compromised client exfiltrates it. Bcrypt doesn't help with any of those. What helps is a fast, deterministic hash — something you can index — plus a server-side secret protecting the stored hashes.

So we use a pepper — a server-side secret. We compute HMAC-SHA256 over the API key using a 64-character random secret stored in AWS Secrets Manager. The stored value is the HMAC output, not the key. An attacker with the database still needs the pepper from Secrets Manager to do anything with those hashes — a completely separate security boundary. And HMAC-SHA256 takes about a microsecond to compute, not a hundred milliseconds.

// Before: bcrypt load-and-compare-all (O(n) * 100ms per key)
for _, stored := range allKeyHashes {
    if err := bcrypt.CompareHashAndPassword([]byte(stored), []byte(apiKey)); err == nil {
        return stored, nil
    }
}

// After: HMAC + indexed lookup (O(1), ~1μs + one DB round trip)
mac := hmac.New(sha256.New, []byte(pepper))
mac.Write([]byte(apiKey))
keyHMAC := hex.EncodeToString(mac.Sum(nil))
return db.VerifyApiKeyHMAC(keyHMAC) // indexed lookup, <1ms

Replacing bcrypt with HMAC alone got auth overhead from ~946ms to ~811ms. Better, but not the kind of better you write a blog post about. Most of that remaining time was network round trips to PostgreSQL — the hash was fast, the wire wasn't. So we kept going.

Zero Database Queries on the Hot Path

I'll spare you the detour where I briefly considered Redis before realizing I was optimizing a 17-key lookup and needed to calm down. The cache design we landed on is simple. Two sync.Map instances live in the auth service: keyCache maps HMAC hashes to key metadata, and userCache maps user IDs to subscription and quota information. When both are populated, an authenticated request never touches the database.

Before: Every Request

Extract Bearer token
DB: load all key hashes
bcrypt.CompareHashAndPassword (each key, ~100ms)
DB: check per-key quota
DB: increment per-key usage counter
3–4 round trips, up to 1.1s of CPU

After: Steady State (cache warm)

Extract Bearer token
HMAC-SHA256 with pepper (~1µs)
sync.Map lookup: keyCache (tens to hundreds of ns)
atomic.AddInt64: local counter (~25ns)
Memory check: usage < limit? (nanoseconds)
Zero database queries

The usage tracking is worth a closer look, because it's where the real database write elimination happens. In the old system, every authenticated request incremented a per-key counter in PostgreSQL. That's a write on the hot path, with all the associated row contention and WAL traffic. Now, we increment a local int64 via atomic.AddInt64 and a background goroutine wakes up every 30 seconds, atomically swaps all the counters to zero, and flushes the totals to the database in a single batch call.

// Simplified — the real flush iterates userCache, where the counter
// lives alongside quota metadata in each cached entry.
func (r *cachedAuthRepository) flush() {
    r.userCache.Range(func(k, v any) bool {
        entry := v.(*userEntry)
        count := atomic.SwapInt64(&entry.localUsageCount, 0)
        if count > 0 {
            // accumulate for batch DB write
        }
        return true
    })
    // single batch call to update all user usage counts
}

Usage numbers can be up to 30 seconds stale, which is fine for monthly quota enforcement but worth understanding. We added one safeguard: when the in-memory counter says a user has exceeded their quota, we do a fresh database lookup before returning 429. This handles plan upgrades — if someone bumps from Starter to Growth mid-session, the cache still thinks their limit is 2,500 until the next DB refresh, so they'd incorrectly hit a wall. The fallback catches it. It adds one DB round trip at the moment that matters most, which is the right trade-off.

We also fixed something embarrassing while we were in there. The old quota model tracked usage per-key, not per-user. Each key had its own counter and its own limit. Which meant that a user who created three keys got three times the quota. Nobody exploited this, as far as I know, but only because nobody thought to try. We were one curious developer away from an unlimited plan at the price of a free tier and some creativity. Seventeen keys across seven users — early days — so nobody noticed. Per-user counters now. Should have been from day one.

The Lazy Migration

We had 17 API keys in production on migration day. A one-off script to backfill HMAC hashes for all of them would have taken about ten minutes to write and thirty seconds to run. We did the lazy migration instead, and I think it was worth the extra complexity.

Why not just run a backfill script? We could have. It would have taken thirty seconds. But then the bcrypt fallback path — which we wrote, and which we'd need if anything went wrong — would never get exercised in production until the one time it actually matters. With lazy migration, every old key that gets used proves the fallback works. It's testing in prod, but the honest kind.

The flow goes like this. Compute the HMAC of the incoming key. Check the cache — miss. Check the database for a matching key_hmac value — miss, because old keys don't have one yet. Fall through to bcrypt, verify against the old hash, succeed. Now kick off an async HMAC backfill, populate the cache, serve the request. Next time that key shows up, it hits the HMAC path directly and never touches bcrypt again.

// Simplified — real signatures differ slightly
hmacHex := computeHMAC(pepper, apiKey)

// 1. Cache (warm path)
if cached, ok := keyCache.Load(hmacHex); ok {
    return cached.(*keyEntry), nil
}

// 2. HMAC indexed lookup (migrated keys)
if key, err := db.VerifyApiKeyHMAC(hmacHex); err == nil {
    keyCache.Store(hmacHex, key)
    return key, nil
}

// 3. Bcrypt fallback (un-migrated keys, once per key)
keyID, err := db.VerifyApiKey(apiKey)
if err != nil {
    return nil, ErrUnauthorized
}

entry := loadKeyEntry(keyID)
go func() {
    if err := db.BackfillHMAC(keyID, hmacHex); err != nil {
        log.Error("hmac backfill failed", "key_id", keyID, "error", err)
    }
}()
keyCache.Store(hmacHex, entry)
return entry, nil

New keys created through the API key manager get their HMAC computed at creation time and never touch the bcrypt path at all. The lazy path is there for the legacy keys, and once they've each been used once, it's never exercised again.

Need vessel data? Check out VesselAPI →

The Rollout

It took three deployment attempts on February 7th. Wrong Secrets Manager config format, then a fix baked into an AMI that hadn't propagated yet, then a missing IAM permission in a different repo. Standard infrastructure bingo. On the third try the server started, we hit /v1/health with a Bearer token, got 200 OK, and briefly celebrated — before realizing the health endpoint doesn't use auth. We'd validated our new authentication system against the one endpoint that skips it. Hit /v1/vessel/{id} instead, watched the bcrypt fallback fire, watched the HMAC backfill, hit it again — sub-10ms. That one counted.

What the Numbers Actually Look Like

Production measurements from February 7th, network overhead stripped out:

Scenario	DB Queries	Auth Overhead
Bcrypt fallback, cold cache	4	~946ms
HMAC lookup, cold cache	2	~811ms
Cache hit	0	<10ms

Under 10 milliseconds with a warm cache. Zero database queries. The auth overhead went from being the dominant cost of every request to being lost in the measurement noise.

Throughput ceiling with bcrypt and 11 keys: under 1 authenticated request per second per core. With HMAC and a cache, authentication is no longer the bottleneck for anything.

The Trade-offs Worth Naming

What changed beyond "it got faster":

The security model is different. With bcrypt, even if you have the database, you can't reverse the hashes. With HMAC, if you get both the database and the pepper, you can verify candidate keys. Our keys have enough entropy that this doesn't matter in practice, but it's a weaker property and I'd rather be upfront about it.

Usage numbers can be stale by up to 30 seconds. A user could overshoot their quota slightly before the flush catches it. At monthly limits measured in thousands, I genuinely don't care. If we ever need per-second rate limiting, we'd use Redis, not this.

There's also a concurrency wrinkle I should own up to: the usage counter itself is atomic, but the dbUsageCount and monthlyLimit fields on the same struct are plain int values read and written without synchronization. Multiple goroutines can read stale values, and worse, the quota-refresh path writes those fields directly on the shared struct without a lock — two concurrent refreshes could clobber each other. I think this is fine at our scale. I'm not entirely sure it's fine. It probably needs a mutex, and I'll probably add one the next time I'm in that file and feeling responsible.

The cache entries do have a TTL — both key and user entries expire after a configured duration, and the lookup re-fetches from the database when they go stale. But there's no active invalidation push. If you revoke a key, it stays valid in memory until that TTL window elapses. At current scale — 17 keys, 7 active users — this is the trade-off that actually kept me up at night, more than the others. We'll add a revocation broadcast before we onboard any enterprise customers. For now, the TTL window is short enough that I can live with it.

Two weeks after migration day, all 17 pre-existing keys have been lazily migrated. New keys get HMAC on creation. The bcrypt fallback path exists in the code and will presumably never run again, but I'm not ready to remove it yet. It's not hurting anyone, and the fallback existing is a different kind of insurance than the fallback being needed.

The performance improvement worked like the math said it would. What I didn't expect was how many other things the migration shook loose — the per-key quota bug, the stale schema assumptions in other services, the concurrency shortcuts we'd been getting away with. You open up one table and suddenly you're looking at every decision you made in the first six months and wondering which ones are still load-bearing. Some of them weren't. Some of them still are.

Self-Hosted Vessel Email Alerts with AWS Lambda and SES

VesselAPI — Wed, 06 May 2026 12:29:45 +0000

The thing you actually want is an email.

Not a dashboard you have to remember to open. Not a webhook you have to write a server for. An email — the kind your bank sends when a charge clears, the kind your airline sends when the gate changes — that quietly arrives in your inbox and tells you the Ever Given just entered Suez, or that one of your chartered tankers' ETA has shifted by six hours.

VesselAPI sends notifications as webhooks and WebSocket messages. That's the right contract for software, the wrong contract for humans. Webhooks are how systems talk. Email is how systems talk to people. The translation layer between them — the thing that turns a webhook stream into vessel port arrival departure email notifications, the sort of thing your inbox already knows how to thread, sort, and search — is small enough to read in one sitting, which is what this post is.

You'll want these installed before starting:

AWS CLI — for SES identity verification and CloudWatch log reads.
AWS SAM CLI — builds and deploys the stack.
Python 3.12 — matches the Lambda runtime; needed if you want to run the example repo's test suite locally.
AWS credentials configured for your target region (aws configure or env vars).
A VesselAPI key on a plan that includes notifications (see the pricing CTA below).

🤖 Setup with Claude Code

Or paste this into a Claude Code session and let it sort the local toolchain out:
check whether the AWS CLI, AWS SAM CLI, and Python 3.12 are installed, and that my AWS credentials are configured for us-east-1 — install or fix anything that's missing

Full source for this post: vessel-api/vessel-email-alerts-aws-sam on GitHub →

The Architecture in One Diagram

vesselapi notification
   |  POST  (HMAC-signed JSON)
   v
API Gateway (HTTP API)
   v
Lambda
   |-- verify HMAC signature
   |-- DynamoDB: have we seen this delivery_id before?
   |-- render email (per event type)
   `-- SES: SendEmail
   v
Your inbox

Five components:

API Gateway HTTP API is the public URL VesselAPI POSTs to. The HTTP API flavor (not REST API) is roughly a third of the price and supports everything we need for one route.
Lambda does the work: verify, deduplicate, render, send.
DynamoDB stores delivery IDs we've already processed so retries from VesselAPI don't double-send. One row per event, 24-hour TTL.
SES sends the mail.
IAM glues the function's permissions together.

The function only runs when a webhook arrives, and at idle the whole thing costs zero.

A note before we start: the events VesselAPI emits — port arrival, port departure, ETA changed, geofence enter/exit — are derived from AIS, not ground truth. AIS-reported destinations and ETAs are entered by the bridge and are sometimes stale, abbreviated ("FOR ORDERS"), or misspelled. Geofence events apply hysteresis to avoid edge-flapping, but you'll still see the occasional false positive — a vessel drifting past a polygon edge in a busy anchorage, a duplicate broadcast from two coastal stations, an ETA tweak that flips back two minutes later. Worth knowing if you're tuning thresholds for an operational workflow; for "tell me when this ship enters that port," the defaults are fine.

Need a VesselAPI key? See the pricing & plans →

Step 1: Verify an Email Address in SES

🤖 Doing it with Claude Code

Skip the console. Ask:
verify the SES identity me@example.com in us-east-1, then poll until it's confirmed
Claude runs aws ses verify-email-identity, then loops on aws ses get-identity-verification-attributes until the status flips to Success.

In the SES console, pick your region (we'll use us-east-1 throughout — change to taste), open Verified identities, click Create identity, and create an Email address identity. AWS sends a confirmation email; click the link.

That's it. We're using a verified email identity rather than a domain because it's instant — no DNS to wait on. For production you'll want a domain identity with DKIM, but for alerts to your own inbox an email identity is fine.

Step 2: Scaffold the Project

The project layout:

vessel-email-alerts/
├── template.yaml
└── src/
    ├── handler.py
    ├── render.py
    └── requirements.txt

requirements.txt is empty — boto3 ships with the Lambda Python runtime, and we're not pulling in a templating library. Plain f-strings handle this.

Here's handler.py in full:

import os
import json
import hmac
import hashlib
import base64
import logging
import boto3
from datetime import datetime, timezone, timedelta
from botocore.exceptions import ClientError

from render import render_email

logger = logging.getLogger()
logger.setLevel(logging.INFO)

# Module-scope clients are reused across warm invocations -- one TLS
# handshake per container, not one per request.
ses = boto3.client("ses")
ddb = boto3.client("dynamodb")

WEBHOOK_SECRET = os.environ["WEBHOOK_SECRET"].encode()
TO_ADDRESS = os.environ["TO_ADDRESS"]
FROM_ADDRESS = os.environ["FROM_ADDRESS"]
IDEMPOTENCY_TABLE = os.environ["IDEMPOTENCY_TABLE"]


def lambda_handler(event, _context):
    headers = {k.lower(): v for k, v in (event.get("headers") or {}).items()}
    raw = event.get("body") or ""
    body: bytes = (
        base64.b64decode(raw) if event.get("isBase64Encoded") else raw.encode("utf-8")
    )

    if not _verify_signature(body, headers.get("x-signature-256", "")):
        return _resp(401, "invalid signature")

    delivery_id = headers.get("x-delivery-id")
    if not delivery_id:
        return _resp(400, "missing X-Delivery-ID")

    if not _claim_delivery(delivery_id):
        # Already processed -- ack so vesselapi stops retrying.
        return _resp(200, "duplicate")

    payload = json.loads(body)
    evt = payload["event"]
    subject, html, text = render_email(evt)

    try:
        ses.send_email(
            Source=FROM_ADDRESS,
            Destination={"ToAddresses": [TO_ADDRESS]},
            Message={
                "Subject": {"Data": subject},
                "Body": {
                    "Html": {"Data": html},
                    "Text": {"Data": text},
                },
            },
        )
    except Exception:
        # Release the claim so the next retry can try again. Without this,
        # any SES failure would silently lose the email.
        _release_delivery(delivery_id)
        raise

    return _resp(200, "sent")


def _verify_signature(body: bytes, sig_header: str) -> bool:
    if not sig_header.startswith("sha256="):
        return False
    expected = sig_header[len("sha256="):]
    mac = hmac.new(WEBHOOK_SECRET, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, expected)


def _claim_delivery(delivery_id: str) -> bool:
    ttl = int((datetime.now(timezone.utc) + timedelta(hours=24)).timestamp())
    try:
        ddb.put_item(
            TableName=IDEMPOTENCY_TABLE,
            Item={
                "delivery_id": {"S": delivery_id},
                "expires_at": {"N": str(ttl)},
            },
            ConditionExpression="attribute_not_exists(delivery_id)",
        )
        return True
    except ClientError as e:
        if e.response["Error"]["Code"] == "ConditionalCheckFailedException":
            return False
        raise


def _release_delivery(delivery_id: str) -> None:
    try:
        ddb.delete_item(
            TableName=IDEMPOTENCY_TABLE,
            Key={"delivery_id": {"S": delivery_id}},
        )
    except ClientError as e:
        logger.error("failed to release claim (delivery_id=%s): %s", delivery_id, e)


def _resp(status: int, body: str):
    return {"statusCode": status, "body": body}

About a hundred lines, abridged a little for the post — the version in the example repo also has structured logging on every branch and a try/except around the JSON parse that returns 400 for malformed bodies. Two lines above are the load-bearing ones: the compare_digest call and the _release_delivery call. They're the difference between a pipeline that's fine on the happy path and one that survives the unhappy paths. We'll come back to both.

And render.py. There's one renderer per event type and a small dispatcher. Three of the seven for shape — port arrival, ETA change, and the generic fallback:

from datetime import datetime


def render_email(evt: dict):
    handler = _RENDERERS.get(evt["type"], _render_generic)
    return handler(evt)


def _vessel_label(v: dict) -> str:
    name = v.get("vesselName") or "Unknown vessel"
    imo = v.get("imo")
    return f"{name} (IMO {imo})" if imo else name


def _fmt_time(iso: str) -> str:
    try:
        return datetime.fromisoformat(iso.replace("Z", "+00:00")).strftime("%Y-%m-%d %H:%M UTC")
    except Exception:
        return iso


def _render_port_arrival(evt):
    v = _vessel_label(evt["vessel"])
    port = evt["data"]["portEvent"]["port"]
    when = _fmt_time(evt["timestamp"])
    subject = f"{v} arrived at {port['name']}"
    text = f"{v} arrived at {port['name']}, {port.get('country', '')} on {when}."
    html = f"<p><strong>{v}</strong> arrived at <strong>{port['name']}</strong>.</p><p>Reported {when}.</p>"
    return subject, html, text


def _render_eta_changed(evt):
    v = _vessel_label(evt["vessel"])
    change = evt["data"]["etaChange"]
    prev = _fmt_time(change["previousEta"])
    cur = _fmt_time(change["currentEta"])
    shift = change["shiftMinutes"]
    subject = f"{v} ETA shifted by {shift} min"
    text = f"{v} ETA changed: {prev} -> {cur} (shift: {shift} minutes)."
    html = f"<p><strong>{v}</strong> ETA shifted by {shift} minutes.</p><p>Previous: {prev}<br>Current: {cur}</p>"
    return subject, html, text


def _render_generic(evt):
    v = _vessel_label(evt["vessel"])
    subject = f"{v}: {evt['type']}"
    body = f"{evt['type']} event for {v} at {_fmt_time(evt['timestamp'])}."
    return subject, f"<p>{body}</p>", body


_RENDERERS = {
    "port.arrival": _render_port_arrival,
    "port.departure": _render_port_departure,        # same shape as arrival
    "eta.eta_changed": _render_eta_changed,
    "eta.destination_changed": _render_destination_changed,
    "position.geofence_enter": _render_geofence,
    "position.geofence_exit": _render_geofence,
}

The other four renderers (departure, destination changed, draught changed, geofence) follow the same shape — pull the relevant fields from evt["data"], format them, return a (subject, html, text) triple. The structure that scales is the dispatcher dict; adding a Slack or Teams channel later is the same pattern with a different output format.

The Two Non-Obvious Parts

It would be tempting to skim past two of those lines. They're the lines that decide whether this thing works or quietly turns into a problem in three months.

HMAC Verification, and Why `hmac.compare_digest`

Every VesselAPI webhook arrives with an X-Signature-256 header: sha256= followed by the hex of HMAC-SHA256(webhook_secret, raw_request_body).

The instinct is to skip this. The Lambda is on HTTPS. The URL is unguessable. Why bother? Because the URL leaks. It ends up in CloudWatch logs, in someone's terminal scrollback, in screenshots, in an AWS console somebody screen-shared on a call. Anyone who knows the URL can POST a fake event to it. Without verification, your inbox is now a free email-sending service for whoever finds it.

The verification is two lines:

mac = hmac.new(WEBHOOK_SECRET, body, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, expected)

The reason it's hmac.compare_digest and not == is the load-bearing detail of this whole post. A naive == short-circuits at the first byte mismatch — meaning the comparison is faster when the strings differ early, slower when they differ late. That timing difference is enough for an attacker to recover the signature one byte at a time, given enough requests. compare_digest always takes the same amount of time regardless of where the strings diverge. Use it.

One byte-handling note: keep body as bytes end-to-end. hmac.new wants bytes, json.loads accepts bytes, and skipping the decode()/encode() round-trip saves you from a class of bugs that only show up when the webhook source ever sends non-UTF-8 content.

Idempotency, and What Happens When SES Fails

VesselAPI retries failed webhook deliveries with exponential backoff. That's a feature: a transient Lambda timeout doesn't lose the event. It's also a problem: the same event can arrive at your Lambda more than once, and without protection you'll send the same email twice. Or three times. Or thirteen.

Every webhook arrives with a unique X-Delivery-ID. We use it as the primary key in a small DynamoDB table with a conditional put: if the row already exists, the put fails atomically, we return 200, and no email goes out. The 24-hour TTL means the table never grows.

We return 200 for duplicates rather than an error. If we returned an error, VesselAPI would retry, the put would fail again, we'd return another error, and we'd loop forever. Returning 200 says "I've handled this," and the chain stops.

The trap, which is easy to fall into and tempting to call "good enough": claim the delivery ID and then call SES. If SES throws — throttle, transient 5xx, suppression-list hit — the claim is now sitting in DynamoDB with no email behind it. The next retry from VesselAPI looks up the delivery ID, finds the row, returns 200 duplicate, and the email is silently lost forever. That's the failure mode _release_delivery exists for: on any SES exception, delete the claim row and re-raise so the retry reaches a fresh slate.

The release itself can also fail (DynamoDB throttling, tiny window, very unlucky). When that happens we log loudly and let the original SES error propagate — the retry will be ack'd as a duplicate this once, but the failure is visible in CloudWatch instead of vanishing into the gap between two AWS services. The unit test for the whole sequence lives in test_handler.py in the example repo — it's the case that catches the bug if you ever refactor the order of those two calls.

Step 3: Deploy with SAM

🤖 Doing it with Claude Code

In the example repo, ask:
deploy this stack with my SES identity me@example.com and a fresh webhook secret
Claude generates the secret with openssl rand -hex 32, runs sam build and sam deploy --guided, and reads the WebhookUrl back to you.

Drop template.yaml next to src/:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Self-hosted vessel email alerts (vesselapi -> Lambda -> SES)

Parameters:
  WebhookSecret:
    Type: String
    NoEcho: true
    Description: The secret you'll configure on the vesselapi notification.
  ToAddress:
    Type: String
    Description: Verified SES recipient (the inbox the alerts go to).
  FromAddress:
    Type: String
    Description: Verified SES sender identity.

Resources:
  IdempotencyTable:
    Type: AWS::DynamoDB::Table
    Properties:
      BillingMode: PAY_PER_REQUEST
      AttributeDefinitions:
        - AttributeName: delivery_id
          AttributeType: S
      KeySchema:
        - AttributeName: delivery_id
          KeyType: HASH
      TimeToLiveSpecification:
        AttributeName: expires_at
        Enabled: true

  EmailSenderFunction:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: python3.12
      Handler: handler.lambda_handler
      CodeUri: ./src
      Timeout: 10
      MemorySize: 256
      Environment:
        Variables:
          WEBHOOK_SECRET: !Ref WebhookSecret
          TO_ADDRESS: !Ref ToAddress
          FROM_ADDRESS: !Ref FromAddress
          IDEMPOTENCY_TABLE: !Ref IdempotencyTable
      Policies:
        - DynamoDBCrudPolicy:
            TableName: !Ref IdempotencyTable
        - Statement:
            - Effect: Allow
              Action: ses:SendEmail
              Resource: !Sub 'arn:aws:ses:${AWS::Region}:${AWS::AccountId}:identity/${FromAddress}'
      Events:
        Webhook:
          Type: HttpApi
          Properties:
            Path: /webhook
            Method: post

Outputs:
  WebhookUrl:
    Description: Paste this into your vesselapi notification's webhook_url.
    Value: !Sub 'https://${ServerlessHttpApi}.execute-api.${AWS::Region}.amazonaws.com/webhook'

Function, API, table, IAM role, log group — about fifty lines of YAML. The equivalent Terraform is noticeably more verbose because it has to express each resource individually instead of leaning on AWS::Serverless::Function's built-in defaults. NoEcho: true keeps the secret out of CloudFormation outputs and the AWS console; the env-var value is still readable to anyone with lambda:GetFunctionConfiguration, which is the usual tradeoff and the reason the production checklist below moves it to Secrets Manager. The ses:SendEmail policy is scoped to the verified FromAddress identity ARN — a compromised function role can't be used to send mail from other identities in the account.

Build and deploy:

sam build
sam deploy --guided \
  --parameter-overrides \
    WebhookSecret=<some-long-random-string> \
    ToAddress=you@example.com \
    FromAddress=you@example.com

--guided walks you through stack name, region, and the IAM confirmation. Pick us-east-1, accept the IAM prompt, and let it run. About 90 seconds later:

Outputs
-----------------------------------------
Key           WebhookUrl
Value         https://abc123xyz.execute-api.us-east-1.amazonaws.com/webhook

Save the URL. For the secret, openssl rand -hex 32 is a sensible default — use the same value for both the SAM parameter and the VesselAPI notification config below.

Step 4: Register the Webhook with VesselAPI

🤖 Doing it with Claude Code
register a vesselapi webhook for IMO 9811000 pointing at the WebhookUrl from the last deploy, use the same secret
Claude pulls the URL out of the SAM stack output, reuses the secret, and POSTs the notification config.

curl -X POST https://api.vesselapi.com/v1/notifications \
  -H "Authorization: Bearer $VESSELAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lambda-email-alerts",
    "imos": [9811000],
    "event_types": ["port.arrival", "port.departure", "eta.eta_changed"],
    "webhook_url": "https://abc123xyz.execute-api.us-east-1.amazonaws.com/webhook",
    "webhook_secret": "<the same secret you passed to SAM>"
  }'

9811000 is the IMO of the Ever Given itself — handy if you want a vessel that moves often and is easy to recognise in your inbox while you verify the pipeline. Swap in the IMOs you actually want to watch. The event_types filter is optional; omit it to get every event type for the watched vessels.

Step 5: Send a Test Event

🤖 Doing it with Claude Code
fire a test event at the lambda-email-alerts notification and tail the CloudWatch logs until it reports sent
Claude hits the test endpoint, follows the log stream, and stops when it sees the success line — or the error line, with a translation of what's actually wrong.

VesselAPI exposes a test endpoint that fires a synthetic event through your full delivery path:

curl -X POST https://api.vesselapi.com/v1/notifications/<id>/test \
  -H "Authorization: Bearer $VESSELAPI_KEY"

A few seconds later, the email should be in your inbox.

When It Doesn't Work the First Time

🤖 Doing it with Claude Code
read the last 5 minutes of CloudWatch logs for the EmailSenderFunction and tell me what's failing
Claude pulls the log stream and surfaces the relevant error — usually one of the two below, before you've finished asking.

It usually doesn't. Two things go wrong on first deploy, in roughly this order:

MessageRejected: Email address is not verified — SES is in sandbox and either the FromAddress or ToAddress isn't a verified identity. Verify both, retry. If you used the same email for both, you only need to verify it once.
invalid signature in the Lambda logs — the secret in the SAM parameter doesn't match the one in the VesselAPI notification. They have to be byte-for-byte identical, including no trailing newlines.

Check the CloudWatch log group at /aws/lambda/<stack-name>-EmailSenderFunction-<hash>.

What This Costs

For a single user with ten watched vessels and a few events a day, in us-east-1 as of April 2026:

Service	Volume	Cost
API Gateway HTTP API	~100 req/mo	$0.0001
Lambda	well inside free tier	$0
DynamoDB pay-per-request	~100 writes/mo	$0.0001
SES	100 emails/mo	$0.01
CloudWatch logs	small	pennies

Total: a few cents to a dollar a month, dominated by SES if you send a lot. Idle cost is zero. AWS prices drift; check the current rates if you scale this beyond personal use.

Going to Production

The deploy above is the right shape for "alerts to my own inbox." For anything wider, four changes — each incremental, none of which break the pipeline above:

Move out of SES sandbox. Request production access in the SES console; AWS Support's initial response usually arrives within 24 hours, full approval can take longer.
Verify a domain identity with DKIM. Send From: alerts@yourdomain.com and have it display as authenticated rather than as a generic AWS noreply.
Wire up bounce and complaint handling. Attach an SES Configuration Set and route Bounce and Complaint events to an SNS topic. A single typo'd ToAddress can otherwise quietly land you on the SES suppression list.
Move the webhook secret to Secrets Manager. A small SAM change; the function reads it on cold start and caches it.

A future post will go deep on each of these. For now, the pipeline you have is sufficient.

Common Questions

How can I receive automatic email alerts when a vessel enters or leaves a port?

Subscribe to VesselAPI's port-event webhook, point it at an AWS Lambda function, and have Lambda format the event and send it via Amazon SES. The result is an email in your inbox each time a tracked vessel arrives at or departs from a port — no dashboard polling and no extra server.

What's the difference between maritime email alerts and API-based vessel monitoring?

API-based monitoring gives your software a stream of events to process programmatically — useful for dashboards, fleet analytics, or automated triggers. Email alerts translate that same stream into something a human reads in their inbox, and are best when one or two people need passive awareness of specific vessels rather than a full dashboard. The two are layers, not alternatives: the API is what your systems react to, the email is what a human reads at 2am.

How much does it cost to run vessel email alerts on AWS Lambda?

For a typical fleet of a few dozen vessels generating tens of port events per day, the cost is essentially zero — well within the AWS Lambda and SES free tiers. Even at 1,000 alerts per month, the total monthly cost is well under one US dollar. See the cost breakdown above for the line items.

Do I need a server to receive vessel email alerts?

No. The pipeline runs entirely on AWS Lambda (serverless) with SES for email delivery and DynamoDB for idempotency. There is no long-running server to provision or maintain.

How do I prevent duplicate emails when AWS retries a webhook?

Use DynamoDB with the webhook event ID as the partition key and a conditional PutItem to deduplicate. If the conditional put fails because the row already exists, return success to the webhook caller without sending the email.

Can I set up alerts for multiple vessels at once?

Yes. Register each vessel as a separate watcher through the VesselAPI dashboard or pass a list of MMSIs to the bulk-subscription endpoint. The same Lambda and SES pipeline serves all of them — the per-vessel cost is negligible.

What Comes Next

This is part 1 of a series on building your own notification consumers on top of VesselAPI webhooks. Part 2 keeps the same Lambda, the same HMAC verify, the same DynamoDB idempotency — and swaps the email renderer for Slack Block Kit, Microsoft Teams Adaptive Cards, or Discord embeds. The dispatcher pattern in render.py is the seam to plug those in: one function per channel, one config flag to pick which one runs.

People often treat maritime email alerts vs API-based vessel monitoring as a choice. They aren't — they're layers. The API integration is the thing your services react to. The email pipeline above it is what a human reads at 2am. Now your inbox knows when your ships move.

DEV Community: VesselAPI

What 'Real-Time' Actually Means for a Vessel Tracking API

The thing you're actually receiving

The latency budget, written down

Pulling positions, properly

Tracking many ships at once

How often should you actually poll?

The thing under the thing

The Email That Arrived Six Hours Late

The thing about email

What an API is actually doing

The honest case for email

The expensive failure mode

What a Port Event Actually Is (And Why Your Timestamps Are Lying to You)

The fridge magnet version

Inferring a thing that didn't actually happen

Why sub-minute matters

Querying it without tripping

The thing under the thing

Drawing Lines on the Ocean

The thing you think you have

Inside, outside, and the hysteresis problem

What the webhook should actually contain

Delivery: the part everyone underestimates

The geofence itself is a choice

The 946-Millisecond Tax: Migrating API Key Auth from Bcrypt to HMAC-SHA256

The 100-Millisecond-Per-Key Tax

Why bcrypt Is the Wrong Tool for API Keys

Zero Database Queries on the Hot Path

Before: Every Request

After: Steady State (cache warm)

The Lazy Migration

The Rollout

What the Numbers Actually Look Like

The Trade-offs Worth Naming

Self-Hosted Vessel Email Alerts with AWS Lambda and SES

The Architecture in One Diagram

Step 1: Verify an Email Address in SES

Step 2: Scaffold the Project

The Two Non-Obvious Parts

HMAC Verification, and Why hmac.compare_digest

Idempotency, and What Happens When SES Fails

Step 3: Deploy with SAM

Step 4: Register the Webhook with VesselAPI

Step 5: Send a Test Event

When It Doesn't Work the First Time

What This Costs

Going to Production

Common Questions

How can I receive automatic email alerts when a vessel enters or leaves a port?

What's the difference between maritime email alerts and API-based vessel monitoring?

How much does it cost to run vessel email alerts on AWS Lambda?

Do I need a server to receive vessel email alerts?

How do I prevent duplicate emails when AWS retries a webhook?

Can I set up alerts for multiple vessels at once?

What Comes Next

HMAC Verification, and Why `hmac.compare_digest`