Vessel monitors

Fire a test webhook event

Delivers a vessel_risk.changed event for this monitor on demand, without screening anything and without consuming a screening unit. Test keys only.

This exists so you can prove your webhook handler works BEFORE you go live. Without it the first event you ever receive is a production one, about a real hull, whenever that hull happens to move — which is not something you can write a handler against or demonstrate to a security reviewer.

The event travels the same path as a real one: same envelope, same HMAC signature, same five-attempt retry schedule, and it appears in GET /api/v1/webhook-deliveries like any other. It is marked simulated: true and carries a sim_-prefixed screening_id, so it can never be mistaken for a real finding, and it is also written to the monitor history so those reads are exercisable too.

Refused with 403 on a live key: a synthetic risk change on a live monitor would enter your compliance record as a real finding about a real vessel.

Check queued_to_endpoints in the response. Zero means no ACTIVE test endpoint subscribes to vessel_risk.changed, which otherwise looks identical to a handler that silently failed.

Required scope: vessel:monitor.

post/api/v1/vessel-monitors/{id}/simulate

Request

  • Base URL: https://arcnautical.com
  • URL: https://arcnautical.com/api/v1/vessel-monitors/{id}/simulate
  • Auth: one of:
    • HTTP bearer
    • API key in header X-ArcNautical-Key

Path parameters

idstring required

Resource identifier.

Headers

Idempotency-Keystring required

Required for resource-creating POST requests. The same key and identical body replay the original response for 24 hours; a different body returns idempotency_conflict.

Request body

change'sanctions_confirmed' | 'sanctions_cleared' | 'vetting_downgraded' | 'ownership_opaque'

Which transition to simulate. Defaults to sanctions_confirmed (GREEN to RED, severity critical), the case worth handling first. The event is built by the same change detector the live monitor uses: the same change rows (label "Sanctions status", RED/AMBER/GREEN, LOW/MEDIUM/HIGH, A-E), the same severity and a previous_verdict, so a handler correct against these is correct against production.

Response

Event queued to your test webhook endpoints.

simulatedtrue required
changestring required
monitor_idstring uuid required
imostring required
event_type'vessel_risk.changed' required
severity'critical' | 'high' | 'low' required
queued_to_endpointsinteger required

How many active test endpoints the event was queued to. ZERO IS THE ONE TO CHECK: it means nothing subscribed, which looks the same from your side as a handler that never fired.

warningstring

Present only when queued_to_endpoints is 0.

Changes

No recorded changes to this operation across all 1 revision of this API.