Webhooks

This page introduces our webhooks, as available since september 2021. If you are integrated with a prior version, please contact us and we'll help you migrate to this version.

Introduction

Webhooks provide a publisher/subscriber model for linking together Web APIs and other services. When an event happens in Dashdoc, a HTTP POST request notification is sent to registered subscribers. The POST request contains information about the event, which makes it possible for the receiver to act accordingly.

Webhooks are more efficient than polling the API frequently and will allow you to receive real-time data about the transports that were updated, in order to process it in your information system.

You can set authorization parameters for security, to ensure the request you receive is sent by Dashdoc.

Below are explanations to help you set up webhooks. You will find details about transport data in the page : Retrieve transport data.

Activation

This is a beta feature. Since it is not activated for all users, you need to contact you Dashdoc project manager to enable it on your account.

(for Dashdoc project managers : the FF is "Enable UI for webhook system V2 in front.")

Getting started

Head to the api section in the settings and you will be able to add webhooks by yourself. You will need to fill the following information:

Name (required) : a name to differentiate your different webhooks
URL (required) : your endpoint's URL
Authorizations (optional) : your endpoint's authorization parameters (parameters format depends on what you expect, it may be an API key, a Bearer token or json data for example)
Events (at least one required) : the events you wish to subscribe to, you can pick as many as you want among all our different events (created, updated, done, ...). Event details are described below.

When are webhooks sent?

Every minute there's a CRON watching transport events in your account. If an event you have subscribed to has occurred, then a webhook is sent to the url you have set in the parameters.

Automatic retries

When a webhook is not received or correctly handled, Dashdoc will retry sending it several times as mentioned in the table below. Dashdoc needs to get an HTTP status 2xx to consider the webhook as received by your system.

Retry number

Delay

1 minute after last failure

5 minutes after last failure

1 hour after last failure

12 hours after last failure

If the 4th retry fails, the webhook sending is paused. You will need to turn it back on from your account's parameter page (in the API section). However, the webhook creation will continue, so that when you resume sending, you will receive all the ones created during the time sending was on hold.

How to turn a webhook back on when it has been paused

Head to your account's parameters page, in the API section. You will see all the webhooks you have created and their statuses. If a webhook is off, you can reactivate it by clicking on the Resume icon on the right of the Sending status: OFF.

All webhooks that were not received yet will be sent again, and new events occurring will trigger new sendings from this webhook.

Logs

Every time a webhook is sent, a log is created. You can consult all logs from you webhook by clicking the Log icon on the right.

Logged information are:

log creation date: when the wehbook was sent, datetime refers to UTC timezone
payload: content that was sent
timeout: true if the webhook didn't receive any response from the target URL within 20 seconds
HTTP status: status code returned by target URL, empty if timeout = true
response headers: response headers from target URL
response body: response body from target URL

Events specificities

Depending on which event you subscribe to, you won't receive the same information inside the payload.

For events created and updated, you will receive the JSON of a transport (i.e. the whole transport data)
For all the other events, you will receive the JSON of a transport_status (just what's changed and some details about the event itself)

Here are all the events (in alphabetical order) you can subscribe to in your account parameters. You will find a short description about what they refer to and, in the next section, you can find an example of the related payload.

acknowledged : trucker has received on mobile the notification about this mission
amended : transport has been updated after it was done (also see delivery_load.amended)
assigned : transport has been assigned to a trucker
break_time : trucker has filled time information about a break he has done or will do during the day
bulking_break_complete : trucker in charge of the post-bulk break part of the transport, has restarted transport from bulk-break site
bulking_break_started : trucker in charge of the pre-bulk break part of the transport, has arrived to bulk-break site
cancelled : transport has been cancelled
checklist_filled : checklist has been filled
confirmed : carrier has confirmed the transport (if you are a shipper of if you chartered a transport)
created : transport has just been created
declined : transport was declined by the carrier (if you are a shipper of if you chartered a transport)
deleted : transport has been deleted
delivery_load.amended : the loads have been updated after the transport was done (also see amended)
departed : trucker has left a site (detected through telematic data)
document.added : A new document has been added by the dispatcher or the trucker on the transport
done : all deliveries have been compeleted
event : Telematics events emitted when geofencing is disabled.
handling_started : loading or unloading has started on site
invoiced : transport has been invoiced to the customer
loading_complete : loading has been performed on loading site (you may have many loading activities in a single transport)
loading_plan_completed : trucker filled loading plan information (in case of multicompartment transport)
on_loading_site : trucker has arrived at loading site
on_the_way : trucker is on it's way to site (when ETA is activated)
on_unloading_site : trucker has arrived at unloading site
paid : transport has been paid by the customer
restored : previously deleted transport has been restored
round_added : ( DEPRECATED, see https://github.com/dashdoc/dashdoc/blob/master/gitbook-api-documentation/webhooks/broken-reference/README.md) (for multiple rounds transports) trucker added a new round in a multiple rounds transport
round_added_v2 : (for multiple rounds transports) trucker added a new round in a multiple rounds transport
round_edited: (for multiple rounds transports) trucker edited a round
round_deleted: (for multiple rounds transports) trucker deleted a round
rounds_complete: (for multiple rounds transports) trucker completed a multiple rounds transport
rounds_started: (for multiple rounds transports) trucker started a multiple rounds transport
sent_to_trucker : notification for this new mission was sent to the trucker's mobile app (doesn't mean he has seen it, see status Acknowledged)
transport_eta_updated : for each transport that has ETA activated, each time the ETA is computed this event is triggered with the new result
truck_wash : truck has been washed
unassigned : transport's trucker has been removed. When the trucker is replaced, this type of event isn't emitted, only `assigned` is
unloading_complete: delivery has been performed on unloading site (you may have many unloading activities in a single transport)
updated : the transport's details have been updated (ex: address has changed, another trucker was assigned, ...)
verified : the transport has been reviewed by a dispatcher after completion and is ready for invoicing (required information are filled, documents are attached, ...)