¶ Status webhook
¶ Introduction
Before webhooks were implemented the best way to retrieve status updates on a transport document, were by calling the state endpoint in the api.
Now we offer an option for the developer to implement a webhook and thus receiving a call to their own api endpoint every time the state of a transportdocument changes.
More than one 'Status event' webhook can be added. It is also possible to delete, modify or disable/enable a 'Status event' webhook(s).
To summarize a message is received when:
- An update causes the document to shifts from state and you are subscribed on the next document state
The status webhook can be configured on the administration page of the website.
Using webhooks is the preferred way, in the future we will no longer support querying the state endpoints.
¶ Setup
At eWastra Admin > Notifications > Status webhook you will find the following screen:
The configuration consist of 5 input fields:
- In the url box you write a valid https url to your api.
We only accept 'https'endpoints for security reasons. If for 3 consecutive days the webhook endpoint can't be reached, the webhook is automatically disabled and a mail is sent to the technical contact mail (if available)
-
In the authorization box you can optionally add a authorization header.
-
A technical contact email address. Is an optional value.
-
Next to giving a valid url you will have to choose which events you are interested in and then select them by clicking on the checkboxes.
-
You can also choose to get the entire transportdocument in the request as well by ticking the "include document with state" checkbox.
¶ Example Setup
¶ Webhook object reference
{
"state": {
"id": 0,
"externalId": "",
"state": 0,
"_stateEnumValues": "0:None, 1:New, 2:Draft, 3:Issued, 4:SignedForPickup, 5:SignedForDelivery, 6:Completed, 8:Cancelled, 10:Deleted",
"cmrNumber": "",
"timestamp": "",
"error": {
"message": "",
"details": [{"key":"value"}]
}
},
"document": {
"_comment": "See Xynaps REST API Reference > definitions > Xynaps.Api.Models.TransportDocument"
}
}
¶ Transport events webhook
¶ Introduction
The transport events webhook is introduced to obtain real-time information about the transport being executed.In comparisment to the status webhook, who focuses on changes in the document state, the transport event webhook focuses on events occuring during transport unlinked to the document state.
More than one 'Transport event' webhook can be added. It is also possible to delete, modify or disable/enable a 'Transport event' webhook(s).
To summarize a message is received when:
- The pre-defined event occurs
- Some events can occur multiple time, others only once, underneath you can find a full description of all the events available.
The following 'Transport events' that can be configured :
| Event | Description | Occurrence |
|---|---|---|
| OrderCreated | When an transport document is created | 1 |
| OrderPlanned | When the transportcompany is assigned to the document | 1 |
| WeightMeasurementAdded | When a weight measurement is added/changed to/on the order (when the driver makes weight measurement changes via the eWastra APP, this webhook is triggered when the driver signs) | 0-n |
| CarrierAssigned | When the carrier is assigned to the order | 1-n |
| DriverAssigned | When the driver is assigned to the order | 1-n |
| OrderStarted | When the order was started, this occurs when the driver presses the button "start order" in the app. | 0-1 |
| NotExecutedAtPickup | When the driver arrived at the pickup location but was not able to complete the pickup of the goods. Triggered by the Unhappy flow. | 0-1 |
| ArrivedAtPickup | When the driver arrives at the pickup location, this occurs when the driver presses the button "arrived" in the app | 1 |
| DriverSignedForPickup | When the has signed the document for pickup | 1 |
| DepartedFromPickup | When driver leaves the pickup location, this occurs when the drivers has collected the signature of the counterparty | 1 |
| TreatmentOperatorChanged | When Treatment Operator was changed (via WEB of API) after the loading process (and signing) and before the unloading process (signed for delivery) | 0-n |
| RemovedAsTreatmentOperator | When Treatment Operator was removed (via WEB of API) from the document, after the loading process (and signing) and before the unloading process (signed for delivery) | 0-n |
| ArrivedAtDelivery | When driver arrives at the delivery location | 1 |
| DriverSignedForDelivery | When driver signs the document at the delivery location | 1 |
| DepartedFromDelivery | When the driver leaves the delivery location, this occurs when the driver has collected the signature of the counterparty. | 1 |
¶ Setup
At Xynaps Admin > Notifications > Webhooks > Transport events you will find the following screen:
The configuration consist of 5 input fields:
- In the url box you write a valid https url to your api.
We only accept 'https'endpoints for security reasons. If for 3 consecutive days the webhook endpoint can't be reached, the webhook is automatically disabled and a mail is sent to the technical contact mail (if available)
- In the authorization box you can optionally add a authorization header.
- The option to add a technical contact mail address. This is an optional value.
- The option to choose the webhook format(Json/Xml).
- A list of all the possible events you can subscribe for.
For the Url and Api Key, the same rules are applicable as for the 'Status' webhooks.
¶ Example Setup (for testing purpose)
Do not forget to save the webhook before it is active or enable it, when it is disabled.