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
1 minute after last failure
2
5 minutes after last failure
3
1 hour after last failure
4
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)

Events you can subscribe to

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)
  • 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 Upgrading to the v2 of the rounds) (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
  • 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, ...)
  • document.added : A new document has been added by the dispatcher or the trucker on the transport

Payload details and examples

Every payload sent will contain the following information:
  • data: full serialized transport
  • type: event category
  • event: full serialized event,
  • version: version of the serializer
Payload example:
exemple_webhook_payload.json
20KB
Code