MIK ship security alert push contract

This page is for the team that operates the system sending the ship security alert (SSA) to the MIK North Sea example. It describes exactly what the receiving side checks, so a sender can be built from it. Everything here is derived from the code that receives the delivery; the last section names the file for each rule. Nothing in it is an operating procedure: the fields follow the public outline of an SSA (SOLAS chapter XI-2 regulation 6 and the ISPS Code) and nothing more.

The receiver is the push ingest mode of the mik-ssa-alerts-v1 data source. The generic mechanics of that mode (address, ordering, deliveries set aside) are in Ingest modes; this page is the contract for this one source.

What you need from the receiving side

One delivery

One request carries one JSON object whose alerts array holds the alerts (normally one). Send an array: an alerts value that is a single object instead of an array is also read, as one alert, but that is not part of the contract. Three headers carry the identity, the signing time and the signature:

Header names are matched case-insensitively, like all HTTP header names. Send Content-Type: application/json.

{
  "alerts": [
    {
      "alertId": "3f0c7c2e-8d1a-4b6e-9a52-7e1d2c4b8f10",
      "mmsi": "000000002",
      "imo": "9000002",
      "shipName": "Demo Aurora Tide",
      "callsign": null,
      "latitude": 51.62,
      "longitude": 2.71,
      "alertedAt": "2026-10-14T00:00:00.000Z",
      "status": "active",
      "provenance": "demo sender"
    }
  ]
}

Fields

Each alert is an object with these fields. Unknown fields are ignored. Types are checked per alert after the delivery is accepted (see Responses).

The receiver does not check a coordinate's range or datum: send WGS 84, and keep latitude within -90 to 90 and longitude within -180 to 180 yourself. An imo or callsign that is absent is stored as null.

Alert and cancel

There is one message shape and one endpoint. The two messages differ only by status:

• Alert: status is "active". A new alertId creates a row.
• Cancel: the same body with the same alertId and status set to "cancelled", sent as a new delivery (new delivery ID). The source writes with upsert on alertId, so the cancel replaces the alert's row. Repeat every required field: the row is replaced as a whole, and alertedAt should keep the alert's original value. The comparison is exact and lower case; any other value is stored as given and is not a cancel.

The watch that raises a detection from alerts leaves out every alert whose status is "cancelled" when it reads, so a cancelled alert raises no detection and does not show in the app. A cancel does not retract a detection or case that the active alert already opened: the watch no longer reads that row, so it takes no action on it. Whether a cancel should retract is not decided by this contract.

Timestamps

• x-ssa-signature-timestamp is Unix seconds in UTC (the same instant everywhere on Earth; there is no time zone to choose).
• The receiver accepts a delivery whose signing time is within 300 seconds of its own clock, in either direction, edges included. Outside that, the answer is 401 push_signature_stale and nothing is read from the body.
• Keep the sender's clock synchronised (NTP). A retry gets a fresh timestamp and the same delivery ID; the timestamp is not part of a delivery's identity.
• alertedAt is a different thing: when the alert was raised on board. The receiver does not compare it with the clock. The example's detection watch, however, only reads alerts whose alertedAt is within the last 900 seconds, so an alert stamped older than that is stored but raises no detection.

Signing

The signature covers these bytes, in this order, with nothing added:

<x-ssa-signature-timestamp>.<x-ssa-alert-id>.<the request body, byte for byte>

The digest is HMAC-SHA256(key = the secret as UTF-8, message = those bytes), sent as hex, optionally prefixed sha256=. A prefix other than sha256= is refused. The body is signed as sent: no canonical form, so sign the final bytes after serialisation and send exactly those.

Because the timestamp and the delivery ID are inside the signed bytes, a captured request cannot be replayed later or under another delivery ID. There is one secret per installed source. The receiver resolves the connection afresh for every delivery, so rotating the secret means editing the connection; the first delivery after that is checked against the new value, and there is no overlap period in which both secrets are accepted.

A worked example. With secret example-shared-secret, delivery ID 7d0f3c2e-5b1a-4a8e-9f61-2c4b8e1d0a93 and timestamp 1791936000 (2026-10-14T00:00:00Z), signing the body shown above on one line without trailing newline gives:

BODY='{"alerts":[{"alertId":"3f0c7c2e-8d1a-4b6e-9a52-7e1d2c4b8f10","mmsi":"000000002","imo":"9000002","shipName":"Demo Aurora Tide","callsign":null,"latitude":51.62,"longitude":2.71,"alertedAt":"2026-10-14T00:00:00.000Z","status":"active","provenance":"demo sender"}]}'
DELIVERY_ID='7d0f3c2e-5b1a-4a8e-9f61-2c4b8e1d0a93'
TS=1791936000
printf '%s.%s.%s' "$TS" "$DELIVERY_ID" "$BODY" | openssl dgst -sha256 -hmac 'example-shared-secret'
# 9e783debd3c597b8cb4b5797c47cc9a4e05b727fda23363d8ef7dc9ba66d0291

The request then carries x-ssa-signature: sha256=9e783debd3c597b8cb4b5797c47cc9a4e05b727fda23363d8ef7dc9ba66d0291.

Responses

The checks run in this order; the first that fails answers.

A 202 means the delivery is queued, not that every alert in it is stored. After acceptance each alert is checked against the field table above: an alert that breaks it (a number where mmsi must be a string, a zone-less alertedAt, a missing required field) is set aside on its own, kept for an hour, and the other alerts of the delivery are written. A sender that wants confirmation that an alert reached the table has to read the table or the source's health in Analytics; the response does not say.

Retries and idempotency

• Same delivery ID, same alerts (the timestamp and signature may differ, and so may the raw body bytes: what is compared is the rows the body maps to, together with the source's manifest, descriptor version and binding ID): answered 202 with "duplicate": true and the original receiptId, and written once. The ID is remembered for one hour by default after the delivery is written or set aside (the retention is a deployment setting); after that a resend is a new delivery.
• Same delivery ID, different alerts: never send this. The receiver refuses the conflict internally and the sender sees 503 push_acceptance_unavailable, which looks like an outage and will repeat for as long as the ID is reused.
• Retry on 429, 503 and network failures, with the same delivery ID and the same body, a fresh timestamp and a growing delay. Do not retry on other 4xx without fixing the cause.
• Deliveries are written in the order they were accepted, one at a time for the source. Alert rows are upserted by alertId, so a late resend of an alert under a new delivery ID rewrites the same row; a cancel sent before a delayed alert would be overwritten by it. Send the cancel after the alert's 202.

Mapping from the public SSA outline

The public outline of a ship security alert (SOLAS chapter XI-2 regulation 6; ISPS Code) is: the alert identifies the ship, gives its position and the time, and states that the security of the ship is under threat or has been compromised. It is sent to a competent authority ashore and not to other ships. Mapped to the contract:

The contract has no course, speed, alert type or free-text field.

Where each rule is enforced

Paths are relative to the repository root; each rule is named by the symbol that holds it, because line numbers move.