Webhooks

CrewPass pushes a webhook to your registered endpoint when data about a crew member on your fleet changes — so you don’t have to poll. Delivery is asynchronous, signed, retried with backoff, and dead-lettered after repeated failure. You receive an event only for a crew member on your fleet, only for an event whose scope you hold, and only when that crew member’s consent allows it — the same gate as the read surface.

How it works

CrewPass keeps watch on the data behind your fleet. When something relevant changes — a certificate finishes processing, compliance moves, a status or profile updates — CrewPass builds the matching event and delivers it to the callback URL you registered, usually within 15 minutes of the change. There is nothing to run on your side beyond an HTTPS endpoint that accepts a POST, verifies the signature, and returns 2xx. Five things worth knowing:

You don’t poll. CrewPass checks your fleet for changes every 15 minutes and pushes what has changed; you react to it.
Delivery is at-least-once. The same event may arrive more than once (e.g. after a retry), so deduplicate on event_id.
Events are not ordered. Treat each one as “this changed, here is how it looks now” rather than as a step in a sequence.
You will not receive a backlog. When your endpoint is first registered you are not sent an event for every certificate already on file. Read the current state through the API once, and webhooks keep you in step from there.
Crew who join your fleet arrive in full. When a crew member is added to one of your vessels, you receive a crew.document.processed for each document they already hold, plus their current compliance, status and profile.

Subscribing

Webhook registration is not self-serve. Ask your CrewPass contact to register your callback URL and the events you want; they set it up for you during onboarding, or whenever you need it changed. CrewPass then issues a webhook signing secret used to sign every delivery (this is separate from your API key; reads are not signed).

The envelope

Every delivery is a JSON body with this shape:

{
  "schema_version": 1,
  "event_id": "evt_abc",
  "event_type": "crew.document.processed",
  "occurred_at": "2026-06-08T10:00:00Z",
  "partner_id": "prt_123",
  "data": { }
}

And these headers:

Header	Value
`X-CrewPass-Event-Id`	The event id (dedupe on this).
`X-CrewPass-Event-Type`	The event type.
`X-CrewPass-Timestamp`	Unix seconds at signing time.
`X-CrewPass-Signature`	`v1=<hex(hmac_sha256(secret, message))>`, where `message` is the timestamp, a dot, then the raw request body bytes.
`X-CrewPass-Schema-Version`	`1`

Signature scheme

The webhook signature signs the timestamp, a dot, then the raw request body bytes ("{timestamp}." + body), with no nonce. Build your receiver’s verification against exactly that string.

Verifying a delivery

Python

import hashlib, hmac

def verify(secret: str, timestamp: str, signature: str, raw_body: bytes) -> bool:
    expected = "v1=" + hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your handler: read the RAW body bytes (do not re-serialize), then:
# verify(SECRET, request.headers["X-CrewPass-Timestamp"],
#        request.headers["X-CrewPass-Signature"], raw_body)

Node

import crypto from "node:crypto";

export function verify(secret, timestamp, signature, rawBody) {
  const expected =
    "v1=" +
    crypto.createHmac("sha256", secret).update(`${timestamp}.` + rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Receiver requirements

Verify the signature against the raw bytes.
Deduplicate on event_id — delivery is at-least-once, so the same event may arrive more than once.
Respond 2xx quickly and process asynchronously.
Anything else is retried with exponential backoff (up to 8 attempts), then dead-lettered. A 4xx (other than 408/429) is treated as a permanent rejection and not retried.

Event catalogue (v1)

Event	Fires when	Scope required
`crew.document.processed`	A document you have not been sent before becomes available, including each document held by a crew member who joins your fleet	`crew:documents:read` (also `crew:medical:read` for a medical-class document)
`crew.document.updated`	Something changes about a document you already have	`crew:documents:read` (also `crew:medical:read` for a medical-class document)
`crew.compliance.changed`	A value in a crew member’s compliance summary changes	`crew:compliance:read`
`crew.status.changed`	Verification or background-check status changes	`crew:status:subscribe`
`crew.profile.updated`	A crew member updates their profile	`crew:profile:read`

crew.document.updated, crew.compliance.changed and crew.status.changed are sent only when a value in their payload changes. A recalculation that leaves every figure the same sends nothing.

`crew.document.processed` / `crew.document.updated`

{
  "crew_unique_id": "crew_001",
  "document_id": "doc_9",
  "type": "document",
  "category": "Medical Certificate",
  "title": "ENG1 Medical",
  "issuer": "Approved Authority",
  "verification_status": "verified",
  "issue_date": "2026-06-01",
  "expiry_date": "2028-06-01",
  "document_number": "E1-998",
  "review_status": "verified",
  "is_expired": false,
  "no_expiry": false,
  "is_current": true,
  "superseded_by": null,
  "classification": {
    "taxonomy_version": "2026-09-17.230e599f",
    "document_class": "medical",
    "category_code": "medical_fitness",
    "catalogue_title": { "id": "…", "name": "ENG1 Medical" },
    "stcw_regulation": null,
    "stcw_codes": [],
    "level": null,
    "is_refresher": null,
    "flag_state": "GB",
    "coc_capacities": [],
    "sources": ["document_category", "medical_record", "catalogue"]
  }
}

The document fields match the documents endpoint, including the classification block. The fields from review_status onwards were added on 2026-09-17. Ignore any fields you don’t need.

`crew.compliance.changed`

{
  "crew_unique_id": "crew_001",
  "vessel_id": "ves_abc",
  "overall_status": "at_risk",
  "requirements_met": 7,
  "requirements_total": 8,
  "requirements_expiring": 1,
  "next_expiry_date": "2026-08-01"
}

`crew.status.changed`

{
  "crew_unique_id": "crew_001",
  "verification_status": "verified",
  "background_check_status": "completed"
}

`crew.profile.updated`

{ "crew_unique_id": "crew_001", "updated_at": "2026-06-08T12:00:00Z" }

Reacting to an event

Every payload carries a crew_unique_id: the join key between CrewPass and your own records. You learn it once, store it against your own crew record, then use it to look up the detail behind any event. Discover a crew member’s crew_unique_id once, then keep it:

GET /api/v2/employers/me/fleet returns the fleet roster, where every crew member arrives with their crew_unique_id.
POST /api/v2/employers/me/crew/lookup resolves a single known crew member to their crew_unique_id.

From then on, an event’s crew_unique_id tells you exactly which of your records changed. An event is a signal, not a full snapshot: the document events carry their metadata inline, and for the others you call the matching read endpoint to fetch the current detail. crew.document.processed and crew.document.updated. The payload already has the document metadata (type, category, issuer, verification status, issue and expiry dates, document number) and its classification, so you can file it straight away. To fetch the file, call GET /api/v2/employers/me/crew/{crew_unique_id}/documents/{document_id}/download and follow the download_url it returns; that link is short-lived, so use it straight away rather than storing it. Both crew_unique_id and document_id come from the event payload.

Document events fire once CrewPass has finished processing a document, not when a crew member uploads it. Expect a short delay between the upload and the event — processing, then up to 15 minutes until the next check.

crew.document.updated covers any change you can see: a re-verification, a corrected date, a newer edition replacing it (is_current, superseded_by), or a change to its classification.

There is no “document removed” event. If a document stops being shared — it is replaced, withdrawn, or goes back for reprocessing — nothing is sent, and your copy will be the last state you were told about. Re-read GET /api/v2/employers/me/crew/{crew_unique_id}/documents periodically, or after a crew.compliance.changed event, if that matters to you.

crew.compliance.changed. The payload is a summary (overall status plus the requirement counts). For the full role, STCW, and medical breakdown, call POST /api/v2/employers/me/crew/{crew_unique_id}/compliance-checks. The overall_status values (compliant, at_risk, non_compliant, no_role) mean the same here as on the compliance read. crew.profile.updated. The event is a change signal, not a diff: it tells you the profile changed, not what changed. Call GET /api/v2/employers/me/crew/{crew_unique_id}/profile to read the current profile. crew.status.changed. The payload carries the new verification_status and background_check_status directly, so update your own record straight from the payload. No follow-up read is required.

Background-check status uses CrewPass’s standardised, provider-agnostic vocabulary.

Get started

Guides

Reference

Webhooks

How it works

Subscribing

The envelope

Signature scheme

Verifying a delivery

Receiver requirements

Event catalogue (v1)

`crew.document.processed` / `crew.document.updated`

`crew.compliance.changed`

`crew.status.changed`

`crew.profile.updated`

Reacting to an event

​How it works

​Subscribing

​The envelope

​Signature scheme

​Verifying a delivery

​Receiver requirements

​Event catalogue (v1)

​crew.document.processed / crew.document.updated

​crew.compliance.changed

​crew.status.changed

​crew.profile.updated

​Reacting to an event

How it works

Subscribing

The envelope

Signature scheme

Verifying a delivery

Receiver requirements

Event catalogue (v1)

`crew.document.processed` / `crew.document.updated`

`crew.compliance.changed`

`crew.status.changed`

`crew.profile.updated`

Reacting to an event