Crewops API reference

Base URL, format and sign-in

• Base URL: https://updates.hawkmason.com. Every path on this page is relative to it.
• Format: JSON in and out. Send Content-Type: application/json with every JSON body; without it the request answers 415. File uploads send the file itself as the body with its own content type.
• Sign-in: Authorization: Bearer <operator code or API key> on every request.
• Scope: the code says which airline it belongs to, so there is no airline parameter. Every list and record is your airline's own.
• Products: the code also says which products your airline holds (Insight, Safety, Academy, Library). A product's endpoints open only if the code includes it.
• From a server: call the API from your own systems. Browsers on other websites are refused by the CORS policy, which allows only hawkmason.com.

The crew code your crews enter in Crewops Crew never opens these endpoints. A crew code answers 403: it is in every crew member's hands and must not read colleagues' data.

export CREWOPS="https://updates.hawkmason.com"
export CREWOPS_KEY="cwk_…"          # an API key, or the operator code

curl -s "$CREWOPS/portal/today" \
  -H "Authorization: Bearer $CREWOPS_KEY"

One key per connected system

Make a key in the operator portal, under Connections, for each system that calls the API: your SMS, your HR system, your training system, your document system. Give each one a name so you know which system it belongs to.

• A key looks like cwk_ followed by 40 hexadecimal characters. It is shown once, when it is made. Crewops stores only its SHA-256 hash.
• A key acts as the operator code it was made with: the same airline, the same products and the same expiry date.
• A key cannot make or revoke keys, and cannot set, rotate, test or delete the webhook. It can read the webhook settings.
• Revoke a key on its own, in the portal, and every other key keeps working. Up to 20 keys can be active at once.
• The portal shows the day each key was last used.

What a refusal means

An error answers JSON with an error field that says what was wrong, for example { "error": "revisionDate YYYY-MM-DD" }.

Today board and webhook settings

The Today board

Each item has a level (bad, warn or info), a kind, a title, a detail, an optional due date and a ref that points to the record: report, risk, audit, change, crew, notice, course, doc or flight.

curl -s "$CREWOPS/portal/today" -H "Authorization: Bearer $CREWOPS_KEY"

{
  "airline": "DEMO",
  "products": ["insight", "safety", "academy", "library"],
  "at": "2026-10-14T07:00:00.000Z",
  "counts": { "bad": 1, "warn": 1, "info": 0 },
  "total": 2,
  "items": [
    { "product": "safety", "level": "bad", "kind": "report_clock",
      "title": "72-hour clock passed", "detail": "DEMO-261010-7KQ2M · Unstable approach",
      "due": "2026-10-13T08:41:00.000Z", "ref": { "report": "DEMO-261010-7KQ2M" } },
    { "product": "academy", "level": "warn", "kind": "qual_expiring",
      "title": "LPC expires within 30 days", "detail": "A1234 · cockpit",
      "due": "2026-11-02", "ref": { "crew": "A1234" } }
  ]
}

Set the webhook

curl -s -X PUT "$CREWOPS/portal/webhook" \
  -H "Authorization: Bearer $OPERATOR_CODE" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://sms.example.com/hooks/crewops",
        "events": ["safety.report.created", "safety.report.updated"] }'

Reports, office records and exports

Report ids look like DEMO-261014-7KQ2M: your airline, the date received (YYMMDD) and five characters. A report's status is one of new, triage, investigation, action or closed.

What a report summary holds

id, type, family (safety or operational), urgent, status, anonymous, crewCode (absent when anonymous), title, date, flightNo, dep, arr, station, receivedAt, clockDue (the end of the 72-hour clock, or null), reportable, photos, rootCause, riskId, sp (the Samn-Perelli score of a fatigue report), source (web for a report sent through the web link) and actionDue (the earliest open action's due date).

What PATCH changes

Send only the fields you change. Add by (up to 60 characters) to name who did it on the report's timeline.

rootCause is one of human_skill, human_decision, human_perception, human_violation, communication_crm, procedure, training, organisation, equipment_technical, environment, external, undetermined. JSON bodies are limited to 64 KB.

curl -s -X PATCH "$CREWOPS/safety/reports/DEMO-261014-7KQ2M" \
  -H "Authorization: Bearer $CREWOPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "action",
        "classification": { "occurrenceClass": "incident", "category": "CABIN",
                            "eventTop": "operational", "reportable": true },
        "action": { "text": "Brief cabin crew on the revised galley stowage check",
                    "owner": "Cabin safety", "due": "2026-10-31" },
        "by": "Safety office" }'

E5X and CSV exports

The E5X file is built and checked against the public ECCAIRS data-bridge schema, so your office can upload it to the ECCAIRS 2 reporting portal or to an authority's ECCAIRS-based system. It carries the date and time, headline, occurrence class, ADREP occurrence category, location, flight number, phase, registration, event type (top level), narrative and reporting history. The operator, aircraft model and aerodrome codes are completed in the ECCAIRS portal. Your office makes the submission; Crewops does not submit. The taxonomy version in the file header is 9.0.0.1 unless you pass ?taxonomy= with another version.

# every report marked mandatory reportable, as one E5X file
curl -s -o reportable.e5x "$CREWOPS/safety/export.e5x?reportable=1" \
  -H "Authorization: Bearer $CREWOPS_KEY"

# the register as CSV
curl -s -o safety.csv "$CREWOPS/safety/export.csv" -H "Authorization: Bearer $CREWOPS_KEY"

Risks, audits and changes

• risks (ids R-…): title, hazard, area, owner, likelihood 1–5, severity A–E, residualLikelihood, residualSeverity, reviewDate, status (open, mitigating, monitoring, closed), sources (report ids). The record comes back with its index and tolerability on the ICAO Doc 9859 5×5 matrix. PATCH also takes addMitigation: { text, owner?, due? }, mitigationDone: index and addSource: reportId.
• audits (ids A-…): title, area, kind (internal, external, authority, supplier), date, auditor, scope, status. PATCH also takes addFinding: { text, level, requirement?, owner?, due? } with level level1, level2 or observation, and updateFinding: { index, rootCause?, cap?, owner?, due?, evidence?, status? }.
• changes (ids C-…): title, description, kind, hazards, owner, plannedDate, reviewDate, status, risks (risk ids). PATCH also takes decision: "approved" or "rejected" with an optional note.

curl -s -X POST "$CREWOPS/safety/office/risks" \
  -H "Authorization: Bearer $CREWOPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Unstable approaches at night", "likelihood": 3, "severity": "C",
        "owner": "Flight safety", "reviewDate": "2027-01-15",
        "sources": ["DEMO-261014-7KQ2M"] }'

Photos and the web report link

Reporters add up to 4 photos to a report (JPEG, PNG or HEIC, up to 10 MB each) from the app or the web form. Your systems read them with the photo path above; each entry in a report's photos list has its file, size and at. The web report link opens the form for crews without the app; share it on your own channels, and rotate it when it has gone further than it should.

Records, notices and courses

crewCode on this page is the crew member's own code in your airline (2–12 capital letters or digits). An audience is { "all": true }, or { "roles": ["cockpit", "cabin"], "codes": ["A1234"] }. JSON bodies are limited to 256 KB.

Import records from your HR or training system

Each record is a crew member with a list of items. kind is one of opc, lpc, line_check, sep, dg, crm, first_aid, route_competence, aerodrome_competence, recurrent_cabin, triennial_cabin, medical, licence, other. Dates are YYYY-MM-DD. label (up to 80 characters) names an item, and note takes up to 200.

curl -s -X POST "$CREWOPS/academy/records" \
  -H "Authorization: Bearer $CREWOPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "records": [
        { "crewCode": "A1234", "role": "cockpit", "name": "A. Pilot",
          "items": [
            { "kind": "lpc", "issued": "2026-05-02", "expires": "2027-05-31" },
            { "kind": "medical", "label": "Class 1", "expires": "2027-02-28" },
            { "kind": "dg", "issued": "2025-11-10", "expires": "2027-11-30" } ] },
        { "crewCode": "C5678", "role": "cabin",
          "items": [ { "kind": "recurrent_cabin", "expires": "2027-03-31" } ] } ] }'

Notices

type is one of crew_notice, safety_bulletin, safety_memo, coordination_sheet, security_notice, information, training_document, revision. url must be https.

curl -s -X POST "$CREWOPS/academy/notices" \
  -H "Authorization: Bearer $CREWOPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "safety_bulletin", "title": "Lithium battery fires in the cabin",
        "body": "Read the revised procedure before your next duty.",
        "dueDate": "2026-10-31", "audience": { "roles": ["cabin"] } }'

Courses

A course takes { title, kind?, mode, dueDate?, minutes?, lessons, quiz?, audience?, by? }. mode is required (with a due date) or self for self-study. kind takes the qualification kinds above.

• lessons, up to 40: { title, kind, url, minutes? }. kind is video (MP4), pdf, link or scorm; url must be https. Upload video and PDF to /academy/files and use the fileUrl, so crews can download the lesson and study offline.
• quiz, optional: { passMark, questions: [{ q, options, answer }] }, with 2–6 options, answer as the index of the right option, up to 60 questions and a pass mark of 50–100 (75 if not given). The exam is graded on the server; the answers never reach the phone. Attempts are kept.

curl -s -X POST "$CREWOPS/academy/courses" \
  -H "Authorization: Bearer $CREWOPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Dangerous goods recurrent", "kind": "dg", "mode": "required",
        "dueDate": "2026-12-15", "audience": { "all": true },
        "lessons": [
          { "title": "Recognising hidden dangerous goods", "kind": "video", "minutes": 18,
            "url": "https://updates.hawkmason.com/academy/file/DEMO/<file>.mp4" } ],
        "quiz": { "passMark": 80, "questions": [
          { "q": "Who must be told first about a spare lithium battery in checked baggage?",
            "options": ["The commander", "The passenger", "Ground handling"], "answer": 0 } ] } }'

SCORM packages

SCORM 1.2 and 2004 packages are uploaded unzipped, one file at a time, and then used as a lesson. The phone keeps the package offline and plays it in the app; the module's own result (passed, completed or failed, with its score) completes the course.

• 1. POST /academy/scorm answers a package id, pkg.
• 2. PUT /academy/scorm/<pkg>/<path> for every file in the package, keeping its path inside the package (no ..). Each answers the file's url.
• 3. POST /academy/courses with a lesson { "kind": "scorm", "url": <the launch file's url>, "files": [every path], "version": "1.2" or "2004" }. The launch file is the one the package's manifest names.

PKG=$(curl -s -X POST "$CREWOPS/academy/scorm" -H "Authorization: Bearer $CREWOPS_KEY" | jq -r .pkg)

cd crm-module/            # the unzipped package
find . -type f | sed 's|^\./||' | while read -r f; do
  curl -s -X PUT "$CREWOPS/academy/scorm/$PKG/$f" \
    -H "Authorization: Bearer $CREWOPS_KEY" --data-binary "@$f" > /dev/null
done
# then publish a course whose lesson is
# { "title": "CRM module", "kind": "scorm", "version": "2004",
#   "url": "https://updates.hawkmason.com/academy/sco/DEMO/$PKG/index.html",
#   "files": ["index.html", "imsmanifest.xml", …] }

Paths with spaces or other special characters must be percent-encoded in the URL.

Controlled documents and revisions

A document has a stable code, such as OM-A (capital letters, digits, dots and dashes). Publishing a revision under an existing code replaces the current revision and keeps the history. JSON bodies are limited to 128 KB.

Publish from your document system

Required: code, revision and revisionDate; a new document also needs title and type (manual, procedure, policy, bulletin, form, checklist, regulation, certificate, other). Optional: category, owner, audience, effectiveDate, changeLog, fileUrl (https), pages, approved, requiresAck, ackDue (the read-by date) and by.

# 1. upload the PDF
FILE_URL=$(curl -s -X POST "$CREWOPS/library/files?name=OM-A%20rev%2014.pdf" \
  -H "Authorization: Bearer $CREWOPS_KEY" -H "Content-Type: application/pdf" \
  --data-binary @om-a-rev14.pdf | jq -r .fileUrl)

# 2. publish the revision with a read-and-confirm
curl -s -X POST "$CREWOPS/library/docs" \
  -H "Authorization: Bearer $CREWOPS_KEY" -H "Content-Type: application/json" \
  -d "{ \"code\": \"OM-A\", \"revision\": \"14\", \"revisionDate\": \"2026-10-14\",
        \"effectiveDate\": \"2026-11-01\", \"fileUrl\": \"$FILE_URL\",
        \"changeLog\": \"8.3.2 revised: stabilised approach criteria\",
        \"requiresAck\": true, \"ackDue\": \"2026-10-31\" }"

Crew post-flight ratings

The ratings crews have chosen to share after their flights, for the dates you ask. A crew member shares only if they switch sharing on in the app.

Each rating has date, flightNo, dep, arr, scale (samn-perelli or kss), value, ratedAt, afterMin, sectors, role, crewCode when the crew member gave it, crewId (a pseudonym of the phone) and receivedAt. Nothing else about the crew member is sent: no sleep, no health entries and no roster beyond the sector rated.

curl -s "$CREWOPS/insight/ratings?from=2026-10-01&to=2026-10-14" \
  -H "Authorization: Bearer $CREWOPS_KEY"

Hear about events as they happen

Set one https endpoint in the operator portal, under Connections, and pick the events it should receive. You can pick only the events of products your airline holds.

The delivery

Each delivery is a POST with a JSON body:

POST /hooks/crewops HTTP/1.1
Content-Type: application/json
User-Agent: Crewops-Webhooks/1
X-Crewops-Event: academy.course.completed
X-Crewops-Signature: t=1791969164,v1=5d0c…e19a

{
  "id": "evt_3f9c0a1b2c4d5e6f7a8b",
  "event": "academy.course.completed",
  "airline": "DEMO",
  "at": "2026-10-14T09:12:44.512Z",
  "data": {
    "courseId": "C-261014-K7QD", "title": "Dangerous goods recurrent", "kind": "dg",
    "crewCode": "A1234", "at": "2026-10-14T09:12:44.501Z",
    "verified": true, "score": 90, "attempts": 1
  }
}

• One try: each event is sent once, with a 5-second timeout and no retries. Answer with a 2xx status quickly and do the slow work afterwards.
• The log: the portal lists the last 20 deliveries with their status, so you can see a failed one and fetch the record through the API.
• Duplicates: keep the id of each event you have handled and ignore one you have seen.
• The secret: it starts with whsec_ and is shown once, when the webhook is made or the secret rotated.

Check the signature

The header x-crewops-signature is t=<unix seconds>,v1=<hex>. v1 is the HMAC-SHA256, keyed with your secret, of the string <t>.<raw body>. Compute it over the body exactly as received, before any JSON parsing, compare it in constant time, and reject a t more than five minutes old.

Node.js (no dependencies)

import http from 'node:http';
import crypto from 'node:crypto';

const SECRET = process.env.CREWOPS_WEBHOOK_SECRET; // whsec_…

function verify(rawBody, header, toleranceS = 300) {
  const parts = Object.fromEntries(String(header).split(',').map((p) => p.split('=', 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceS) return false;
  const expected = crypto.createHmac('sha256', SECRET).update(`${t}.${rawBody}`).digest('hex');
  const given = String(parts.v1 ?? '');
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

http.createServer((req, res) => {
  let raw = '';
  req.setEncoding('utf8');
  req.on('data', (chunk) => (raw += chunk));
  req.on('end', () => {
    if (!verify(raw, req.headers['x-crewops-signature'] ?? '')) return res.writeHead(400).end();
    const { id, event, airline, at, data } = JSON.parse(raw);
    // remember id, queue the work, answer within 5 s
    res.writeHead(204).end();
  });
}).listen(8080);

Python (Flask)

import hashlib, hmac, json, os, time
from flask import Flask, request

SECRET = os.environ["CREWOPS_WEBHOOK_SECRET"].encode()  # whsec_...
app = Flask(__name__)

def verify(raw_body: bytes, header: str, tolerance_s: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > tolerance_s:
        return False
    expected = hmac.new(SECRET, f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

@app.post("/hooks/crewops")
def crewops_hook():
    raw = request.get_data()  # the body exactly as received
    if not verify(raw, request.headers.get("x-crewops-signature", "")):
        return "", 400
    event = json.loads(raw)  # id, event, airline, at, data
    # remember event["id"], queue the work, answer within 5 s
    return "", 204