Webhooks
Last updated
Last updated
Webhooks are user-defined HTTP callbacks that receive events for the subscribed event types. Webhook notifications are asynchronous, the order is not guaranteed.
Events are categorised into event types. Events occur due to changes in the state of a resource, such as when a voyage is updated. When an event occurs, the registered applications are notified via HTTP POST. The POST contains the event details, including the event type that caused the event.
When an application receives the event, it must respond with a 200-level HTTP status code.
When a webhook subscription is made, through the resource WebhookSubscription, for a Dataloy object, BunkerOrder for instance, the subscribed webhook will be pushed with all the changes that occurred to the subscribed object and its object hierarchy. So if a PortCall of the subscribed BunkerOrder is updated the webhook will be notified.
The Remarks are not part of the webhook process. It is not possible to get notifications of changes in Remarks.
The Dataloy webhook event type is a concatenation of the following attributes:
Resource name (Document, Voyage, ..)
Operation type (C,U, D create, update, delete)
Object key
The user can subscribe to a webhook for a given event, for example:
Automatic Deactivation of subscription
If the subscribing system is unavailable or takes too long to respond, the server will deactivate the subscription after attempting 5 times (once a minute). The number of attempts and the interval between each attempt can be configured.
Deactivated subscriptions cannot be reactivated, a new subscription must be created if needed.
Email alert when a subscription is de-activated: Add the desired email address (e.g. to the IT ops team) to the API user (in User Administration) to receive an email notification if a subscription is de-activated.
The message sent to the subscribed endpoint is set in the body of the POST method. The message is a JSON object and has the following structure:
The attributes have the following meaning:
With API 3.9 the following new functionalities have been introduced:
Possibility to be notified of changes via email
Possibility to customize the JSON pushed as Adjust Number of Fields to be Returned from a Request
Possibility to filter changes that have to be pushed via expressions
Possibility to filter changes that have to be pushed via scripts
To be notified via email in the WebhookSubscription must be specified the channelInfo property with channelType EMAIL and the URL with the email address:
channelType can be EMAIL or HTTP if HTTP is set the URL attribute must contain the endpoint where to push notifications.
Through the attribute JSON of WebhookSubscription is possible to specify which attributes of the object must be pushed (see Adjust Number of Fields to be Returned from a Request). The value of JSON must be encoded with Base64.
For instance, if the subscription is for the object BunkerOrderLine a possible value for the JSON attribute could be:
that encoded will be
In this way the sub-object in the attribute resource will be smaller:
Through the attribute expression of WebhookSubscription is possible to write a Java expression against the object changed. At runtime If the expression return true the notification will be sent, otherwise no.
For instance, if the subscription is done for the object BunkerOrderLine a possible expression could be:
that for any changes at any BunkerOrderLine object will check if the unit price is not null and its value is between 10 and 100, if yes the notification will be sent.
In the expression must be used the variable dlpObject to refer to the changed object, the object will contain the new values. If the expression needs to check also the previous values of the object, the variable oldDlpObject can be used.
For instance:
that will check if the new extra cost of a BunkerOrder is greater than the previous one.
If you want to be notified when an attribute change value from null to not null:
The old values will be accessible only for those Dataloy object changed via Dataloy API.
Contact Dataloy to have info regarding scripts.
In version 3.16 (and later) it is possible to decide if a webhook subscription should only be notified on changes to the object subscribed. So for instance making a subscription for the Voyage object, the changes that will occur to linked objects, like PortCall, Cargo, etc, will be not notified. To achieve this behaviour a new boolean attribute called onlyMainObject in WebhookSubscription has been added, setting it to true only the changes for the subscribed will be sent.
A new endpoint in WebhookSubscription POST:sendFailedNotifications has been added to resend manually the failed webhook notification.
In version 5.23 (and later) it is possible to decide if a webhook subscription should only be notified with the raw object, without the envelope payload. To achieve this behavior a new boolean attribute called rawObject in WebhookSubscription has been added, setting it to true the raw object will be sent.
A new attribute xsl has been added which allows you to store an XSL stylesheet to transform the subscribed object to XML. The value of the field must be encoded with Base64. This is part only of Enterprise API.
In order to not get notified by the changes done by the user of the subscription the attribute notSendMyChanges can be set to true.
GET /WebhookSubscription
Get a list of WebhookSubscription objects. Filter to avoid huge amounts of data (see Filtering documentation for examples).
GET /WebhookSubscription/{key}
Get a single WebhookSubscription object.
Example GET Return Body
since API 3.9:
POST /WebhookSubscription
Create a new WebhookSubscription.
Examples
Create a subscription to get notifications when the BunkerOrder with primary key 243896793 is updated:
Create a subscription to get notifications when any BunkerOrder is updated:
Create a subscription to get notifications when a BunkerOrder is created:
Create a subscription to get notifications when the BunkerOrder with primary key 243896793 is deleted:
Create a subscription to get notifications when any BunkerOrder is deleted:
Create a subscription to get notifications when any BunkerOrder is updated via email, since API 3.9:
Create a subscription to get notifications only when a Voyage object is changed, since API 3.16:
PUT /WebhookSubscription/{key}
Only the following attributes can be updated:
unsubscribed
url
webhookUsername
webhookPassword
Since API 3.9 is possible to change also these other attributes:
channelInfo
json
expression
dlpAlertScript
scriptParameterValues
useMsg
To unsubscribe a subscription the following JSON must be sent. It is not possible to update the subscription if it has been unsubscribed:
DELETE /WebhookSubscription/{key}
To delete a WebhookSubscription first it has to be unsubscribed. It is not possible to delete WebhookSubscription that got Webhook notifications, regardless that it has been unsubscribed or not.