{"_id":"59778bb932f043002002f5df","category":{"_id":"59778bb932f043002002f5d5","version":"59778bb932f043002002f5d3","project":"5425e663ffd4411c319a65b4","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-09-29T20:18:57.785Z","from_sync":false,"order":1,"slug":"reference","title":"Reference"},"project":"5425e663ffd4411c319a65b4","user":"5425e31affd4411c319a65b1","version":{"_id":"59778bb932f043002002f5d3","project":"5425e663ffd4411c319a65b4","__v":1,"createdAt":"2017-07-25T18:19:37.272Z","releaseDate":"2017-07-25T18:19:37.272Z","categories":["59778bb932f043002002f5d4","59778bb932f043002002f5d5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.5.0","version":"2.5"},"__v":0,"updates":["566320dea504730d00deb70c"],"next":{"pages":[],"description":""},"createdAt":"2014-10-03T03:05:11.662Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"never","params":[],"url":""},"isReference":false,"order":17,"body":"[Webhooks](https://en.wikipedia.org/wiki/Webhook) make it possible for your application to be notified of important system events, as soon as these take place within Onfleet.\n\nWhile you are generally able to create as many webhook entries as you'd like, remember that a single webhook always targets a single trigger. The following triggers are available:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"ID\",\n    \"h-1\": \"Name\",\n    \"0-0\": \"0\",\n    \"1-0\": \"1\",\n    \"2-0\": \"2\",\n    \"3-0\": \"3\",\n    \"4-0\": \"4\",\n    \"5-0\": \"5\",\n    \"0-1\": \"taskStarted\",\n    \"1-1\": \"taskEta\",\n    \"2-1\": \"taskArrival\",\n    \"3-1\": \"taskCompleted\",\n    \"4-1\": \"taskFailed\",\n    \"5-1\": \"workerDuty\",\n    \"h-2\": \"Description\",\n    \"0-2\": \"Task started by worker.\",\n    \"1-2\": \"Worker ETA less than or equal to `threshold` value provided, in seconds.\",\n    \"2-2\": \"Worker arriving, at or closer than `threshold` value provided, in meters.\",\n    \"3-2\": \"Task completed by worker.\",\n    \"4-2\": \"Task failed.\",\n    \"5-2\": \"Worker status changed (`0` for off-duty, `1` for on-duty).\",\n    \"6-0\": \"6\",\n    \"7-0\": \"7\",\n    \"6-1\": \"taskCreated\",\n    \"7-1\": \"taskUpdated\",\n    \"6-2\": \"New task created.\",\n    \"7-2\": \"Task updated, including assignment, feedback and attachment (photo, signature) changes.\",\n    \"8-0\": \"8\",\n    \"8-1\": \"taskDeleted\",\n    \"8-2\": \"Task deleted.\",\n    \"9-0\": \"9\",\n    \"9-1\": \"taskAssigned\",\n    \"9-2\": \"Task assigned to worker.\",\n    \"10-0\": \"10\",\n    \"10-1\": \"taskUnassigned\",\n    \"10-2\": \"Task unassigned from worker.\",\n    \"h-3\": \"Includes\",\n    \"0-3\": \"`taskId`, `data.task`\",\n    \"1-3\": \"`taskId`, `data.task`, `etaSeconds`\",\n    \"2-3\": \"`taskId`, `data.task`, `distance`\",\n    \"3-3\": \"`taskId`, `data.task`\",\n    \"4-3\": \"`taskId`, `data.task`\",\n    \"5-3\": \"`workerId`, `status`, `data.worker`\",\n    \"6-3\": \"`taskId`, `data.task`\",\n    \"7-3\": \"`taskId`, `data.task`\",\n    \"8-3\": \"`taskId`\",\n    \"9-3\": \"`taskId`, `data.task`\",\n    \"10-3\": \"`taskId`, `data.task`\",\n    \"h-4\": \"Limitations\",\n    \"0-4\": \"None\",\n    \"3-4\": \"None\",\n    \"4-4\": \"None\",\n    \"5-4\": \"None\",\n    \"6-4\": \"None\",\n    \"7-4\": \"None\",\n    \"8-4\": \"None\",\n    \"9-4\": \"None\",\n    \"10-4\": \"None\",\n    \"1-4\": \"Limit of 10 webhooks. Each will fire once per task, at most once every 30 seconds, when threshold is met.\",\n    \"2-4\": \"Limit of 10 webhooks. Each will fire once per task, at most once every 30 seconds, when threshold is met.\",\n    \"11-0\": \"12\",\n    \"11-1\": \"taskDelayed\",\n    \"11-2\": \"Task is delay time is greater than or equal to `threshold` value provided, in seconds.\",\n    \"11-3\": \"`taskId`, `data.task`, `delay`\",\n    \"11-4\": \"Limit of 10 webhooks, applies only to active tasks, will only fire once.\"\n  },\n  \"cols\": 5,\n  \"rows\": 12\n}\n[/block]\nWebhooks can be maintained via dashboard or API. All standard, non-validation requests from Onfleet to you are made via ```POST```.\n\nIn addition to the properties from the *Includes* column above, the JSON body we will ```POST``` to your ```url``` will include a ```time``` property along with ```triggerId``` and ```triggerName``` so you may overload the same ```url``` on your application as required. In addition, full objects will be provided in the `data` property, as relevant. Note that all other properties not relevant to the trigger may be provided as `null`.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Validation\"\n}\n[/block]\n\nAll URLs are validated through a simple token exchange mechanism so we may trust that you actually control the target server. Note that validation happens right at webhook creation, meaning that we will issue a request to you before successfully registering the webhook.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Automatic validation\",\n  \"body\": \"If you use [Zapier](https://zapier.com/) webhooks instead of your own backend's, validation will be automatic. [RequestBin](http://requestb.in/) has also been whitelisted to simplify development.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Retry\"\n}\n[/block]\nAny failed requests will be retried in  30-minute cycles, up to one full day. A failed request is any non-```200``` response that a webhook request gets from your application. If there are more than 300 consecutive failures, the webhook will be automatically disabled. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Testing\"\n}\n[/block]\nYou may find a tool like [ngrok](https://ngrok.com/) or [RequestBin](http://requestb.in/) useful to test your webhook integrations, however in order to pass the initial validation step, you will need to ensure that your tool of choice allows you to respond to our validation request, unless it has been automatically validated.\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"Create webhook\"\n}\n[/block]\nBody parameters\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"url\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The URL that Onfleet should issue a request against as soon as the trigger condition is met. It must be HTTPS and have a valid certificate.\",\n    \"1-0\": \"trigger\",\n    \"1-1\": \"number\",\n    \"1-2\": \"The number corresponding to the trigger condition on which the webhook should fire.\",\n    \"2-0\": \"threshold\",\n    \"2-1\": \"number\",\n    \"2-2\": \"Optional. For trigger `1`, the time threshold in seconds; for trigger `2`, the distance threshold in meters.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nThe ```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. \n\nIn a Node.js/CoffeeScript environment, the following would suffice:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"server.get '/onfleet/taskStart', (req, res, next) ->\\n\\tres.send req.params.check\\n  return next()\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nTo create a new webhook, provide a verifiable ```url``` and ```trigger```.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X POST \\\"https://onfleet.com/api/v2/webhooks\\\" \\\\\\n     -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\" \\\\\\n     -d '{\\\"url\\\":\\\"https://11ec4a02.ngrok.com/onfleet/taskStart\\\",\\\"trigger\\\":0}'\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": \\\"9zqMxI79mRcHpXE111nILiPn\\\",\\n    \\\"count\\\": 0,\\n    \\\"url\\\": \\\"https://11ec4a02.ngrok.com/onfleet/taskStart\\\",\\n    \\\"trigger\\\": 0\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"List webhooks\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X GET \\\"https://onfleet.com/api/v2/webhooks\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\"\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n    {\\n        \\\"id\\\": \\\"ZnVRY8rdfUwNPjHQy2QthtxZ\\\",\\n        \\\"count\\\": 7,\\n        \\\"url\\\": \\\"https://11ec4a02.ngrok.com/onfleet/driverNearby\\\",\\n        \\\"trigger\\\": 2\\n    },\\n    {\\n        \\\"id\\\": \\\"9zqMxI79mRcHpXE111nILiPn\\\",\\n        \\\"count\\\": 3,\\n        \\\"url\\\": \\\"https://11ec4a02.ngrok.com/onfleet/taskStart\\\",\\n        \\\"trigger\\\": 0\\n    }\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n```count``` provides a total number of successful requests made for a webhook.\n[block:api-header]\n{\n  \"type\": \"delete\",\n  \"title\": \"Delete webhook\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -i -X DELETE \\\"https://onfleet.com/api/v2/webhooks/ZnVRY8rdfUwNPjHQy2QthtxZ\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\"\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"HTTP/1.1 200 OK\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"webhooks","type":"basic","title":"Webhooks"}
[Webhooks](https://en.wikipedia.org/wiki/Webhook) make it possible for your application to be notified of important system events, as soon as these take place within Onfleet. While you are generally able to create as many webhook entries as you'd like, remember that a single webhook always targets a single trigger. The following triggers are available: [block:parameters] { "data": { "h-0": "ID", "h-1": "Name", "0-0": "0", "1-0": "1", "2-0": "2", "3-0": "3", "4-0": "4", "5-0": "5", "0-1": "taskStarted", "1-1": "taskEta", "2-1": "taskArrival", "3-1": "taskCompleted", "4-1": "taskFailed", "5-1": "workerDuty", "h-2": "Description", "0-2": "Task started by worker.", "1-2": "Worker ETA less than or equal to `threshold` value provided, in seconds.", "2-2": "Worker arriving, at or closer than `threshold` value provided, in meters.", "3-2": "Task completed by worker.", "4-2": "Task failed.", "5-2": "Worker status changed (`0` for off-duty, `1` for on-duty).", "6-0": "6", "7-0": "7", "6-1": "taskCreated", "7-1": "taskUpdated", "6-2": "New task created.", "7-2": "Task updated, including assignment, feedback and attachment (photo, signature) changes.", "8-0": "8", "8-1": "taskDeleted", "8-2": "Task deleted.", "9-0": "9", "9-1": "taskAssigned", "9-2": "Task assigned to worker.", "10-0": "10", "10-1": "taskUnassigned", "10-2": "Task unassigned from worker.", "h-3": "Includes", "0-3": "`taskId`, `data.task`", "1-3": "`taskId`, `data.task`, `etaSeconds`", "2-3": "`taskId`, `data.task`, `distance`", "3-3": "`taskId`, `data.task`", "4-3": "`taskId`, `data.task`", "5-3": "`workerId`, `status`, `data.worker`", "6-3": "`taskId`, `data.task`", "7-3": "`taskId`, `data.task`", "8-3": "`taskId`", "9-3": "`taskId`, `data.task`", "10-3": "`taskId`, `data.task`", "h-4": "Limitations", "0-4": "None", "3-4": "None", "4-4": "None", "5-4": "None", "6-4": "None", "7-4": "None", "8-4": "None", "9-4": "None", "10-4": "None", "1-4": "Limit of 10 webhooks. Each will fire once per task, at most once every 30 seconds, when threshold is met.", "2-4": "Limit of 10 webhooks. Each will fire once per task, at most once every 30 seconds, when threshold is met.", "11-0": "12", "11-1": "taskDelayed", "11-2": "Task is delay time is greater than or equal to `threshold` value provided, in seconds.", "11-3": "`taskId`, `data.task`, `delay`", "11-4": "Limit of 10 webhooks, applies only to active tasks, will only fire once." }, "cols": 5, "rows": 12 } [/block] Webhooks can be maintained via dashboard or API. All standard, non-validation requests from Onfleet to you are made via ```POST```. In addition to the properties from the *Includes* column above, the JSON body we will ```POST``` to your ```url``` will include a ```time``` property along with ```triggerId``` and ```triggerName``` so you may overload the same ```url``` on your application as required. In addition, full objects will be provided in the `data` property, as relevant. Note that all other properties not relevant to the trigger may be provided as `null`. [block:api-header] { "type": "basic", "title": "Validation" } [/block] All URLs are validated through a simple token exchange mechanism so we may trust that you actually control the target server. Note that validation happens right at webhook creation, meaning that we will issue a request to you before successfully registering the webhook. [block:callout] { "type": "info", "title": "Automatic validation", "body": "If you use [Zapier](https://zapier.com/) webhooks instead of your own backend's, validation will be automatic. [RequestBin](http://requestb.in/) has also been whitelisted to simplify development." } [/block] [block:api-header] { "type": "basic", "title": "Retry" } [/block] Any failed requests will be retried in 30-minute cycles, up to one full day. A failed request is any non-```200``` response that a webhook request gets from your application. If there are more than 300 consecutive failures, the webhook will be automatically disabled. [block:api-header] { "type": "basic", "title": "Testing" } [/block] You may find a tool like [ngrok](https://ngrok.com/) or [RequestBin](http://requestb.in/) useful to test your webhook integrations, however in order to pass the initial validation step, you will need to ensure that your tool of choice allows you to respond to our validation request, unless it has been automatically validated. [block:api-header] { "type": "post", "title": "Create webhook" } [/block] Body parameters [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "url", "0-1": "string", "0-2": "The URL that Onfleet should issue a request against as soon as the trigger condition is met. It must be HTTPS and have a valid certificate.", "1-0": "trigger", "1-1": "number", "1-2": "The number corresponding to the trigger condition on which the webhook should fire.", "2-0": "threshold", "2-1": "number", "2-2": "Optional. For trigger `1`, the time threshold in seconds; for trigger `2`, the distance threshold in meters." }, "cols": 3, "rows": 3 } [/block] 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. In a Node.js/CoffeeScript environment, the following would suffice: [block:code] { "codes": [ { "code": "server.get '/onfleet/taskStart', (req, res, next) ->\n\tres.send req.params.check\n return next()", "language": "javascript" } ] } [/block] To create a new webhook, provide a verifiable ```url``` and ```trigger```. [block:code] { "codes": [ { "code": "$ curl -X POST \"https://onfleet.com/api/v2/webhooks\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\" \\\n -d '{\"url\":\"https://11ec4a02.ngrok.com/onfleet/taskStart\",\"trigger\":0}'", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"id\": \"9zqMxI79mRcHpXE111nILiPn\",\n \"count\": 0,\n \"url\": \"https://11ec4a02.ngrok.com/onfleet/taskStart\",\n \"trigger\": 0\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "get", "title": "List webhooks" } [/block] [block:code] { "codes": [ { "code": "$ curl -X GET \"https://onfleet.com/api/v2/webhooks\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\"", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "[\n {\n \"id\": \"ZnVRY8rdfUwNPjHQy2QthtxZ\",\n \"count\": 7,\n \"url\": \"https://11ec4a02.ngrok.com/onfleet/driverNearby\",\n \"trigger\": 2\n },\n {\n \"id\": \"9zqMxI79mRcHpXE111nILiPn\",\n \"count\": 3,\n \"url\": \"https://11ec4a02.ngrok.com/onfleet/taskStart\",\n \"trigger\": 0\n }\n]", "language": "json" } ] } [/block] ```count``` provides a total number of successful requests made for a webhook. [block:api-header] { "type": "delete", "title": "Delete webhook" } [/block] [block:code] { "codes": [ { "code": "$ curl -i -X DELETE \"https://onfleet.com/api/v2/webhooks/ZnVRY8rdfUwNPjHQy2QthtxZ\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\"", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "HTTP/1.1 200 OK", "language": "http" } ] } [/block]