Webhooks
Overview
Though the TechLink Services API provides tremendous capabilities in client-to-service integration, sometimes service-to-client communications can make work flow more efficient. This is where webhooks come into play.
The TechLink Services webhooks are real-time, event-based data connections from TechLink Services to your system. Using webhooks, you can be notified when events occur with your data, such as one of your work orders having it status changed, having a document or photo uploaded to it, having a technician arrive on-site, etcetera.
In short, the API allows you to talk to TechLink, and webhooks allow TechLink to talk to you.
Environments
Webhooks are implemented in multiple environments to facilitate development and testing in a consequence-free (or consequential) system.
Sandbox
Webhooks are implemented in a sandboxed testing environment, so that development working with sample data can be performed. The base address for the sandboxed webhooks/API is: https://sandbox.techlinksvc.net/
The sandboxed environment is populated with a copy of the production data. Note that this copy may be somewhat out-of-date, so recently-created job sites, work orders, and user accounts may not be present. The sandboxed environment can be refreshed with more current data on request.
Production (Live Portal)
The production webhooks/API are implemented on the live TechLink Services portal. The base address for the production environment is: https://portal.techlinksvc.net/
Webhooks from the production environment will be working with live data - work orders are handled by actual Project Managers and fulfilled by actual Installers. Production environment webhook destinations should be fully developed, well-tested, and efficiently executed.
Configuration and Testing
Webhooks can be set up through the TechLink portal UI.
To configure webhooks via the portal UI, log into the portal and go to your Company Details page. Open the Webhooks tab. From there, select Add New Webhook Registration. A new registration section will appear, where you can configure the webhook registration to your liking. See the Webhook Structure section for details.
Note that you can also test webhooks from the portal UI; follow the instructions displayed on the page.
Webhook Structure
Webhooks are delivered via an HTTP POST request, to whatever endpoint URL is defined in the webhook event registration. Multiple events can be sent to a single endpoint, or a single event can be sent to multiple endpoints.
Event Registration Properties
Type: The webhook event type is defined here. The types (such as "work order note added" or "site created") are listed in the event descriptions below. There are two special event types available during configuration, "(all current webhooks)" and "(any webhooks)". "(all current webhooks)" means that every available event, at the time of the registration, will be directed at the endpoint. "(any webhooks)" means that webhooks of any type, even those added after the registration was created, will be sent to that endpoint (i.e., a true wildcard).
URL: An absolute URL/URI defining the endpoint for the webhook POST request. Absolute means fully-qualified, i.e. "https://yourserver.com/techlink_webhook/" and such.
Token: An arbitrary (and optional) string value that will be sent with the POST request as an "X-Token" header. This is for your own use, as a layer of validation that the POST request did originate with the webhook system.
Enabled: A boolean indicating whether or not this registration is active (will be sent events) or not. By default it is true.
Notes
Webhooks do not execute in real-time - they may fire some minutes after an event actually occurred.
A webhook event will attempt to POST three times, each a minute or two apart. If a webhook event fails to send three times, it will not be attempted again.
Accounts
The following user account webhooks are available.
Account Created
A user account has been created for you.
The webhook event will be POSTed in the following format:
{
"event": "account created",
"data": {
(user object - see API Documentation - Get Client Users for definition)
}
}
Account Updated
One of your user accounts has been updated.
The webhook event will be POSTed in the following format:
{
"event": "account updated",
"data": {
(user object - see API Documentation - Get Client Users for definition)
}
}
Sites
The following job site webhooks are available.
Site Created
A job site has been created for you.
The webhook event will be POSTed in the following format:
{
"event": "site created",
"data": {
(site object - see API Documentation - Get Site Details for definition)
}
}
Site Updated
One of your job sites has been updated with new information.
The webhook event will be POSTed in the following format:
{
"event": "site updated",
"data": {
(site object - see API Documentation - Get Site Details for definition)
}
}
Work Orders
The following webhooks are supported for work orders.
Work Order Created
A work order has been created for you.
The webhook event will be POSTed in the following format:
{
"event": "work order created",
"workorder_id": "123456",
"data": {
(work order object - see API Documentation - Get Work Order Details for definition)
}
}
Work Order Updated
One of your work orders has been updated.
The webhook event will be POSTed in the following format:
{
"event": "work order updated",
"workorder_id": "123456",
"data": {
(work order object - see API Documentation - Get Work Order Details for definition)
}
}
Work Order Status Changed
One of your work orders has had its status changed. Status changes occur when the work order has entered a new, discrete phase of its life cycle.
The webhook event will be POSTed in the following format:
{
"event": "work order status change",
"workorder_id": "123456",
"old_status_code": "60",
"old_status": "Scheduled",
"new_status_code": "70",
"new_status": "Tech On Site"
}
Status codes and their descriptions:
Statuses will not necessarily be linearly executed - the status may jump around and cycle through patterns.
Note that some statuses can be transitory - only momentarily used on the way to another status.
Work Order Scheduled
One of your work orders has been scheduled, i.e., has had an install date associated with it.
The webhook event will be POSTed in the following format:
{
"event": "work order scheduled",
"workorder_id": "123456",
"start": "2019-03-27 09:00:00"
}
Note that the work order status may end up as Scheduled - this webhook event just indicates a changing of the scheduled installation time.
Work Order Assigned
One of your work orders has been assigned to an installer.
The webhook event will be POSTed in the following format:
{
"event": "work order assigned",
"workorder_id": "123456",
"planned_tech_name": "John Smith",
"planned_tech_phone": "123-4567-8900"
}
Note that this is also triggered when a work order is unassigned from an installer, in which case it will have blank technician fields.
Work Order Tech On-Site
One of your work orders has had a technician arrive on-site.
The webhook event will be POSTed in the following format:
{
"event": "work order tech on-site",
"workorder_id": "123456",
"tech_name": "John Smith",
"tech_phone": "123-4567-8900",
"time": "2019-01-23 01:23:45 PDT"
}
Note that time field will be localized to the job site's timezone.
Work Order Tech Off-Site
One of your work orders has had the technician leave the job site, either with the intent of returning or in a state of work completion.
The webhook event will be POSTed in the following format:
{
"event": "work order tech off-site",
"workorder_id": "123456",
"disposition": "complete", [Or "return" if a return trip is planned]
"time": "2019-01-23 01:23:45 PDT"
}
Note that time field will be localized to the job site's timezone.
Work Order Closed
One of your work orders has been closed, and is considered to be complete.
The webhook event will be POSTed in the following format:
{
"event": "work order closed",
"workorder_id": "123456"
}
Work Order Cancelled
One of your work orders has been cancelled.
The webhook event will be POSTed in the following format:
{
"event": "work order cancelled",
"workorder_id": "123456"
}
Work Order Note Added
A note has been added to one of your work orders.
The webhook event will be POSTed in the following format:
{
"event": "work order note added",
"workorder_id": "123456",
"data": {
(work order note object - see API Documentation - Get Work Order Notes for definition)
}
}
The note content may contain HTML or rich text.
Work Order Photo Added
A photo has been added to one of your work orders.
The webhook event will be POSTed in the following format:
{
"event": "work order photo added",
"workorder_id": "123456",
"data": {
(work order photo object - see API Documentation - Get Work Order Photos for definition)
}
}
Note that the URL provided may be time-limited. For resource storage, immediate access and saving is recommended.
You can also retrieve the (raw) photo using the API's Get (Raw) Work Order Photo endpoint.
Work Order Close-Out Question Answered
A close-out question has been answered for one of your work orders.
The webhook event will be POSTed in the following format:
{
"event": "work order question answered",
"workorder_id": "123456",
"data": {
(work order individual question object - see API Documentation - Get Work Order Close-Out Questions for definition)
}
Note that only the answered question is sent as the payload, not all questions.
Work Order (Completed) Close-Out Document Added
A completed close-out document has been added to one of your work orders.
The webhook event will be POSTed in the following format:
{
"event": "work order close-out document added",
"workorder_id": "123456",
"data": {
(work order document object - see API Documentation - Get Completed Work Order Close-Out Documents for definition)
}
}
Note that the URL provided may be time-limited. For resource storage, immediate access and saving is recommended.
You can also retrieve the (raw) document using the API's Get (Raw) Completed Work Order Close-Out Document endpoint.
Work Order Client Document Added
A client document has been added to one of your work orders.
The webhook event will be POSTed in the following format:
{
"event": "work order client document added",
"workorder_id": "123456",
"data": {
(work order document object - see API Documentation - Get Work Order Client Documents for definition)
}
}
Note that the URL provided may be time-limited. For resource storage, immediate access and saving is recommended.
You can also retrieve the (raw) document using the API's Get (Raw) Work Order Client Document endpoint.
Work Order Task Added
A task has been added to one of your work orders.
The webhook event will be POSTed in the following format:
{
"event": "work order task added",
"workorder_id": "123456",
"data": {
(task object - see API Documentation - Get Work Order Tasks for definition)
}
}
Work Order Task Updated
One of your work order's tasks has been updated.
The webhook event will be POSTed in the following format:
{
"event": "work order task updated",
"workorder_id": "123456",
"data": {
(task object - see API Documentation - Get Work Order Tasks for definition)
}
}
Work Order Task Deleted
A task has been deleted from one of your work orders.
The webhook event will be POSTed in the following format:
{
"event": "work order task deleted",
"workorder_id": "123456",
"task_id": "12345"
}