Audience

This document is designed to be used by Windward’s teams (product, R&D, customer success). It serves as an updated knowledge resource for all webhook related features, providing detailed workflows and logic explanations regarding the inner functions on the platform.
Some sections, mainly the appendixes, can be used as step-by-step guides to assist new customers with their initial implementation and exploration of the system.

Objective

Windward platform continuously monitors each vessel and analyzes its behavior. Users can enrich their own application by integrating their backend and exposing near-real-time insights in their frontend client.
Setting up Windward’s API access is a quick integration process aimed to trigger a webhook call (from Windward’s platform to external endpoint). This webhook mechanism is triggered whenever Windward detects a relevant activity (vessel detected behavior). Our customer success team will set up the destination endpoint through which the payload will be delivered. Additionally, an API call can be used to update the webhook’s destination endpoint. Authentication Token authorization is supported as “bearer” type only. The string provided to our teams will be configured as a static value for the desired webhooks. Our platform does not support token expiration for this type of integration, therefore, any changes will require manual adjustment to ensure service continuity.

See generic information regarding bearer implementation here.
For Token validation visit https://jwt.io/ - paste your key and review its properties including timestamp expiration and more.

Network

Production environment is set up with 2 static public ip addresses. All webhooks will be sourced through these addresses. Specific configuration details will be provided by our customer success team during setup sessions.

Responses and Retry Mechanism

All webhooks are directed at specific endpoints on customers’ systems.
When a webhook is triggered, the payload of the respective function is delivered to the destination endpoint and a response is collected and logged. The expected response for a successful payload delivery is “200 OK” (based on the http standards available here). Any status code other than 200 will drive a retry attempt for the relevant payload. In the event of an error in delivery (either network issues of application availability), a retry mechanism is activated for each failed payload separately. This mechanism triggers additional attempts (up to 5 total retries, in 30 seconds intervals). To ensure service continuity it is advised to check the WAF configuration so that retry attempts will not trigger a threshold and a possible block on similar requests.

Troubleshooting process:

Once logged in to the webapp, navigate to the "webhook portal" tab.

You can review the endpoint configuration to make sure the desired event type is selected, or switch to the "Logs" sub-tab to review the latest messages sent from Windward's platform to your server.

If an expected payload was not successfully delivered, you may select the relevant row from the log view table, scroll down to the "Webhook Attempts" table at the button of the page, click the action menu icon on the right side of the row and click "Resend".

For any assistance in troubleshooting reach out to customer success teams which will pull the relevant log records and provide an analysis on Windward’s side.

Webhook Structure

Common Fields

Fields	Type	Description	Can be null?	Comment
EventTypes	Array	An array that holds the different event types. See Supported Activity Types	No	At this stage, only one event type is returned.
Action Type	String	Created/ Changed / Deleted	No
VesselID	String	Windward’s unique vessel ID	No
VesselName	String	The vessels’ name	No
IMO	String	The vessel’s IMO number	Yes
MMSI	String	The vessel’s MMSI number	Yes
ActivityID	String	Windward’s Activity ID	No
Flag	String	The flag, as reported by the vessel	Yes
Class	String	The vessel’s Class	No
StareDateTime	String	The timestamp of the event	No
duration	String	The duration of the activity	Yes	Will only be available for continuous activities, and will be returned in the “updated” event type only
firstBlip	Array [Float]	Long and lat coordinates of the vessel at the start of the activity
lastBlip	Array [Float]	Long and lat coordinates of the vessel at the end of the activity		Will only be available for continuous activities, and will be returned in the “updated” event type only
PortName	String	The reported port name	No	used for "Port Call" activity
PortCountry	String	The port’s country	No	used for "Port Call" activity
Locode	String	The port’s polygon Locode	No	used for "Port Call" activity
SecondVessel: ID	String	The ID of the second vessel involved in the meeting		used for "Meeting" activity
SecondVessel: imo	String	The IMO of the second vessel involved in the meeting		used for "Meeting" activity
MMSI	String	The MMSI of the second vessel involved in the meeting		used for "Meeting" activity
minBeaufortLevel	Int	The lowest Beaufort scale measured	Yes	used for "Weather" activity
maxBeaufortLevel	Int	The highest Beaufort scale measured	Yes	used for "Weather" activity
OldDestination	String	The name of the previous reported destination	Yes	used for "Destination Change" activity
NewDestination	String	The name of the new reported destination	Yes	used for "Destination Change" activity
newDestinationCountry	String	The country name of the new reported destination	Yes	used for "Destination Change" activity
newDestinationLocode	String	The Locode of the new destination	Yes	used for "Destination Change" activity
newDestinationName	String	The name of the new reported destination	Yes	used for "Destination Change" activity
newEta	String	The datetime representing the new ETA	Yes	used for "ETA Change" activity
oldEta	String	The datetime representing the previous ETA	Yes	used for "ETA Change" activity
portName	String	The name of the port	Yes	used for "In Polygon" activity
portCountry	String	The name of the port country	Yes	used for "In Polygon" activity

Supported Activity Types

Activity Type	Documentation/Explanation
BAD_WEATHER	Vessel sailing in bad weather event
DARK_ACTIVITY	A vessel conducting dark activity
DESTINATION_CHANGE	Vessel reported a change in destination
DEVIATION_FROM_PATTERN_FIRST_IN_POLYGON	First time in new area
ETA_CHANGE	Vessel reported an ETA change
LOW_SPEED_DRIFTING	Vessel conducting a drifting activity
LOW_SPEED_FISHING	Fishing operation
LOW_SPEED_OTHER	Slow speed activity
MEETING	Ship-to-Ship operation event
PORT_CALL	A vessel at port event
LOW_SPEED_ANCHORING	Anchored vessel