Webhooks Set- up & Triggers
Webhooks are an advanced feature that allows organizations to be notified as soon as special trigger conditions are met, via an HTTP POST to the URL specified.
To manage or create webhooks from the Onfleet dashboard, start by logging in as the admin user. Select the "Settings" icon on the upper-right corner of the dashboard, then click on "API & Webhooks" from the settings window.
To create a new webhook:
1. Click the "+" button located on the bottom right corner of the "Webhooks" box.
2. (optional) Label the webhook with a distinctive name.
3. Select which trigger you would like for your webhook. See Available Webhook Triggers below for the full list.
4. If the trigger uses a threshold, enter the threshold value.
5. Enter the URL where webhooks updates should be pushed
6. Validate and create the webhook.
Available Webhook Triggers
Each webhook targets a single trigger. You can create as many webhooks as you need, and several webhooks can point to the same URL. The triggers below are available today.
Task Triggers
Trigger | ID | Fires when |
taskCreated | 6 | A new task is created. Does not include tasks created via dashboard task import. |
taskUpdated | 7 | A task is updated, including completion details, attachments (signatures, photos) and recipient feedback. |
taskAssigned | 9 | A task is assigned to a driver, team or organization. Does not fire when a task is assigned at creation. |
taskUnassigned | 10 | A task is unassigned from a driver. |
taskStarted | 0 | A driver starts a task. |
taskEta | 1 | The driver's ETA is at or below your threshold (in seconds). |
taskArrival | 2 | The driver is at or closer than your threshold distance (in meters). |
taskDelayed | 12 | An active task's delay is at or above your threshold (in seconds). |
predictedTaskDelay | 30 | An assigned task's predicted delay is at or above your threshold (in seconds). Evaluated when the driver starts tasks in their queue. |
taskPredictedEta (new) | 31 | A task's Predicted ETA is at or above your threshold (in seconds). Accepted range: 1800 to 28000 seconds. |
taskCompleted | 3 | A task is marked as successful. |
taskFailed | 4 | A task is marked as failed. |
taskCloned | 13 | A task is cloned via the dashboard or API. taskCreated does not fire for cloned tasks. |
taskDeleted | 8 | A task is deleted. |
Route Plan Triggers
Trigger | ID | Fires when |
routePlanCreated | 22 | Route Optimization creates a Route Plan. One payload is sent per Route Plan. |
routePlanUpdated | 26 | A Route Plan is changed. |
routePlanAssigned | 28 | A Route Plan is assigned. |
routePlanUnassigned | 27 | A Route Plan is unassigned. |
routePlanStarted | 23 | A Route Plan is started. |
routePlanDelayed | 29 | A Route Plan is marked as delayed. |
routePlanCompleted | 24 | A Route Plan is completed. |
Driver Triggers
Trigger | ID | Fires when |
workerDuty | 5 | A driver goes on duty or off duty. |
workerCreated | 15 | A new driver is created. |
workerUpdated | 25 | A driver's information is updated. |
workerDeleted | 16 | A driver is deleted. |
Recipient SMS Triggers
Trigger | ID | Fires when |
smsRecipientResponseMissed | 14 | A recipient replies to an SMS notification, but your organization is unable to handle it at that time. |
SMSRecipientOptOut | 17 | A recipient replies "STOP" to opt out of SMS communications. |
Job Completion Triggers
Trigger | ID | Fires when |
autoDispatchJobCompleted | 18 | A Team Auto-Dispatch calculation is completed. |
routeOptimizationJobCompleted | 20 | A Route Optimization job is completed. |
taskBatchCreateJobCompleted | 19 | An async batch task creation job is completed. |
Note: Threshold-based triggers (taskEta, taskArrival, taskDelayed and taskPredictedEta) are limited to 10 webhooks each. For payload details and field definitions for every trigger, see the Webhooks API documentation.
Webhook Validation
To ensure ownership of the URL used, Onfleet requires validation before the webhook is enabled.
The URL value provided will receive a GET request from our servers, with a check query parameter. You need to respond to our validation request with exactly this value, untouched, as a simple string response; you can refer to the Create a Webhook documentation for code examples.
To get started quickly with Onfleet webhooks, feel free to use the webhooks tool from our open-source repository which creates webhook endpoints for you.
Note: Zapier and RequestBin URLs are whitelisted and are automatically validated.
Webhook Secrets
As an additional security measure, Onfleet will automatically generate a Webhook secret to ensure the request received by your webhook URL is from Onfleet. The Webhook secret can be found under the "API & Webhooks" section of the admin settings by selecting "Show Secret".
For more information on Webhook authentication please go here.
Scoped Webhooks
A Scoped Webhook is a webhook created using a Scoped API key.
If your organization currently integrates with another software to create or track your Onfleet tasks, you can use a Scoped API key to create a Webhook that would limit the access of an integrator to your organization's task information.
You can find more information on how to use a Scoped API Key to create a Scoped Webhook by going to our API Documentation.