vWork API v5 Templated Jobs - Creation Only (Stable Release)
We have broken our API documentation into three parts. The following documentation is for creating jobs from existing vWork templates.
If you need full control over your jobs and don't want to reference your templates, then you should use our job API documentation.
If you need to access something other than jobs, then you should use our vWork API documentation
vWork software is centred on the use of templates to manage multiple job types. This makes it easy for website users to create the same job type over and over again.
The use of templates is not supported via our standard API. You define what a job looks like when you send the job XML to the API.
However, the Templated Job API does use the templates saved in your vWork account. In essence, you supply us with the template name (or the template ID) that you wish to use when creating the job, we will then inherit everything we can from the template; Step names, Custom Field Logic, Custom Labels, Duration, Tags, Time Windows, etc.
The only other information you may need to supply are any values that you wanted to include on the job creation. This may include a customer ID, or a customer name, an address for the job, any custom field values you want to supply, or invoice line items that need to appear on the job.
You are welcome to use the Templated Job API for your initial job creation, and then our standard API for updating, cancelling, downloading or deleting jobs. Our standard API also includes many other non-job related functions such as managing hazards, groups, messages, assets, users, etc..
The base URL for our API is: https://api.vworkapp.com/
You need to have a vWork account with the API enabled to obtain an API key.
If you already have an API enabled vWork account, you can create your own API Key here on the integrations page.
If you do not yet have a vWork account, please get in touch with us.
There is a list of frequently asked questions on our helpdesk page as well as a brief intro to the vWork API. If you get stuck, please don't hesitate to send us an email at: support@vworkapp.com
Do you want to be emailed when we make a change to the API? You can signup for notifications about the vWork API here. We don't email very often, but we will notify you about any changes, as well as notifications about both planned and unplanned outages.
By default, the vWork API requires users to support gzip HTTP response compression on all requests. This is enabled by setting a 'Accept-Encoding: gzip' header on requests, and properly handling the 'Content-Encoding' header on responses. For more information please see http://en.wikipedia.org/wiki/HTTP_compression.
Failure to specify HTTP compression may result in requests being rejected with a HTTP response of type 406/Not Acceptable.
When providing dates you must supply them in the following ISO8601 format: YYYY-MM-DDTHH:MM:SS.
The API uses GMT by default. In order for you to use your local time you must also supply a timezone on your ISO8601 date (e.g. 2011-12-25T22:32:07+10).
Finally, you may need to url encode the date string depending on your environment (e.g. 2011-12-25T22%3A32%3A07%2B10)
Here is an explanation of some of the error codes you may see when developing your integration.
HTTP 401 (Authorization Required) is returned if you don’t have permission to call this service. Check that your api_key is correct.
HTTP 404 (Not Found) is returned if the resource requested was not found.
HTTP 406 (Not Acceptable) is returned if the request did not include headers for http compression.
HTTP 422 (Unprocessable Entity) is returned if vWork wasn’t able to process the request body, for example when the XML is incorrectly formatted.
HTTP 429 (Too Many Requests) is returned if vWork is unable to process the number of requests you have sent, please throttle your queries and try again in a minute or two.
HTTP 500 (Server Error) is returned if a logic error was found, such as a required field is missing.
Please note, that quite often the reason for a 422 error is included in the body of the XML that is returned to you. This is often an excellent source of debugging information, here is a sample that says a date time custom field value was not a valid date and time.
<?xml version='1.0' encoding='utf-8' ?>
<errors>
<error>
<attribute>custom_fields.custom_field</attribute>
<message>'tomorrow night' must be a valid ISO8601 value.</message>
</error>
</errors>For general information about Webhooks, see http://en.wikipedia.org/wiki/Webhook
To minimise the requirement for a vWork API consumer to frequently poll the API for updates, vWork can send webhook callbacks to a predetermined endpoint URL when a change is made.
Depending on the information contained in the webhook, the consumer may then choose to perform a GET on that specific resource to retrieve the updated resource.
You can select to recieve a webhook when any of the following actions occur: Job Created, Job Assigned, Job Unassigned, Job Reassigned, Job Declined, Job Accepted, Job Rescheduled, Job Started, Job Completed, Job Deleted, Job Paused, Job Unpaused, Step Completed, Step Uncompleted, Custom Field Updated, Invoice Updated, User Created, User Updated, User Deleted, Proof of Delivery (POD) Created, and Proof of Delivery Deleted.
Note that if a single action triggers multiple events (for example, creating an assigned job will trigger both a Job Created and a Job Assigned webhook), the order of these events is not guaranteed. But if multiple separate changes happen, those events will be sent in order.
Please also note, that the Job Reassigned webhook only triggers if the job is reassigned from the jobs tab or the mobile app. If a job is reassigned by dragging it to a new worker on the schedule, this will result in two webhooks, a Job Unassigned followed by a Job Assigned.
You can configure your webhook endpoint, select the format you prefer (JSON or XML), as well as select what actions should trigger a webhook to be sent, from the admin section of the vWork website: https://go.vworkapp.com/html_client/admin/webhooks
The callback endpoint will be provided and maintained by the API consumer, and should support SSL/TLS encryption.
Given the potential for a relatively high volume of callbacks, it is strongly advised that the consumer employ asynchronous background task execution and/or a message queueing pattern for handling incoming Webhook callback events. Platforms such as Delayed Job, Resque and RabbitMQ are some well-known examples of asynchronous processing platforms.
(If you are using our legacy webhooks, turning on the new webhooks will not turn off the old ones. Please email support@vworkapp.com when you are ready for us to turn off the old webhooks. NB: If you update your webhook endpoint on the website, this will update the endpoint for both new and old webhooks.)
An example of a Job Created XML webhook is below:
<?xml version="1.0"?>
<event>
<transaction_id>617d4a74-7a19-11e6-bf7a-55542dc9080d</transaction_id>
<event_type>job_created</event_type>
<event_time>2016-09-14T01:20:10Z</event_time>
<resource>Job</resource>
<resource_id>9876234</resource_id>
<account_id>7829</account_id>
<request_user_type>User</request_user_type>
<request_user_id>123</request_user_id>
</event>An example of a Job Created JSON webhook is below:
{
"transaction_id": "617d4a74-7a19-11e6-bf7a-55542dc9080d",
"event_type": "job_created",
"event_time": "2016-09-14T01:20:10Z",
"resource": "Job",
"resource_id": 9876234,
"account_id": 7829,
"request_user_type": "User",
"request_user_id": 123
}An example of a Step Completed XML webhook is below:
<?xml version="1.0"?>
<event>
<transaction_id>63d75660-7a1a-11e6-8d5a-474090628a07</transaction_id>
<event_type>step_completed</event_type>
<event_time>2016-09-14T01:27:24Z</event_time>
<resource>Step</resource>
<resource_id>25062292</resource_id>
<account_id>8723</account_id>
<request_user_type>User</request_user_type>
<request_user_id>123</request_user_id>
<event_location>
<lat>-36.86524165519692</lat>
<lng>174.7806050757642</lng>
</event_location>
<data>
<step_name>Start Job</step_name>
<completed_at>2016-09-15T02:00:12Z</completed_at>
<job_id>8626773</job_id>
</data>
</event>An example of a Step Completed JSON webhook is below:
{
"transaction_id": "63d75660-7a1a-11e6-8d5a-474090628a07",
"event_type": "step_completed",
"event_time": "2016-09-14T01:27:24Z",
"resource": "Step",
"resource_id": 25062292,
"account_id": 8723,
"request_user_type": "User",
"request_user_id": 123,
"event_location": {
"lat": -36.86525719794106,
"lng": 174.780580958473
},
"data": {
"step_name": "Start Job",
"completed_at": "2016-09-15T02:58:31Z",
"job_id": 8621412
}
}Webhooks will always contain the following fields:
transaction_id - an internal vwork audit ID, can be ignored
event_type - the action that triggered the webhook
event_time - the time the server recieved the event, this may not be the time of the event (in UTC)
resource - the resource that was updated: job, custom field, proof of delivery, step or user.
resource_id - the vWork ID for the resource that was updated.
account_id - the ID of your vWork account (can be useful if you are recieving webhooks for multiple accounts.)
In addition, some webhooks may contain these extra fields:
request_user_type - Who triggered the action: a user, or a customer portal user. Will not be present for API events or automatic events (like an auto decline event).
request_user_id - The ID of the user who triggered the action. Will not be present for API events or automatic events (like an auto decline event).
resource_third_party_id - The 3rd Party ID for the resource that was updated. Only present when a 3rd Party ID exists.
data_worker_id - The ID of the worker the job is assigned to. Present on Job Accepted, Job Assigned and Job Reassigned Webhooks.
data_worker_name - The name of the worker the job is assigned to. Present on Job Accepted, Job Assigned and Job Reassigned Webhooks.
data_field_label - The label of the custom field that was updated. Only present on Custom Field Updated webhooks.
data_field_value - The new value of the custom field that was updated. Only present on Custom Field Updated webhooks.
data_field_type - The type of the custom field that was updated. Only present on Custom Field Updated webhooks.
event_location_lat - the lattitude of the worker's location when they completed the action. Only present on Step Completed, Step Uncompleted, Job Start and Job Complete when a location is available.
event_location_long - the longitude of the worker's location when they completed the action. Only present on Step Completed, Step Uncompleted, Job Start and Job Complete when a location is available.
data_step_name - The name of the step that was updated. Only present on Step Completed and Step Uncompleted webhooks.
data_completed_at - The time when the step was completed (in UTC). Only present on Step Completed webhook.
data_job_id - The job that the POD, step, or custom field is for. Only present on POD Created, POD Deleted, Custom Field Updated, Step Completed, and Step Uncompleted webhooks.
data_paused_at - The time when the job was paused (in UTC). Only present on Job Paused webhooks.
data_unpaused_at - The time when the job was unpaused (in UTC). Only present on Job Unpaused webhooks.
data_signed_at - When the POD was signed. Only present on POD Created and Deleted webhooks.
data_signed_by - Who Signed the POD. Only present on POD Created and Deleted webhooks.
data_name - The name of the user. Only present on User Created and User Updated webhooks.
data_email - The email address of the user. Only present on User Created and User Updated webhooks.
data_phone - The phone number of the user. Only present on User Created and User Updated webhooks.
data_notes - Any notes saved against the user. Only present on User Created and User Updated webhooks.
The vWork Webhook notifier will expect a HTTP/200 status code in the HTTP response from the callback endpoint provided by the API consumer. If a non-200 response is received, or the endpoint cannot be reached, vWork will discard the callback event.
Callbacks will always be sent in the order they were created; in the event of a single callback failure as described above, the failing callback will be discarded, but the Webhook notifier will attempt to send all subsequent callbacks in the normal manner.
Various factors could cause a callback to be discarded, such as an internet connection dropout or a momentary server problem. vWork recommends that the API consumer implement a low-frequency polling mechanism (e.g. hourly or daily) to “fill in” any data which may have been missed as a result of a discarded callback.
We implement a layer of security which is simple to consume. Using your api key and a "signature" that is calculated and sent with the Webhook, you can verify the contents of a Webhook as being authentic and un-tampered.
Webhooks are signed with a signature generated by taking an HMAC-SHA-256 hex digest of the raw HTTP Body of the Webhook post, using your api key as the secret.
This signature will be sent with the Webhook post in the header X-Vwork-Webhook-Signature-Hmac-Sha-256. If you chose not to implement this measure, you can just ignore the header.
As an example, the HMAC signature is generated in Ruby with this code:
OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), api_key, webhook.body)If your api key is 123 and the Webhook request body contents are:
<job><name>test</name></job>using code like this:
OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), '123', '<job><name>test</name></job>')the signature for this Webhook would be:
7643b9dbcab60ae6ae32e5683e1fae1db105bd31f1f0b5d51e5b773235359ff0Please note, that when calculating the HMAC SHA we strip out all line breaks and whitespace from the body of the webhook, in order for you to get the same result, you will need to do the same.
Also the webhook body should be ASCII encoded.
Postman is an API development and testing tool. We encourage our customers to use Postman as a way of quickly learning the capabilities of the vWork API. vWork support staff can often provide sample Postman collections or Postman friendly XML samples to assist you.
You can download a copy from here: https://www.getpostman.com/