Posted Time Webhook

You can register a webhook using the WiseTime Connect API to be notified whenever a user posts time to your team. When that happens, WiseTime will send a POST request to your webhook, with a JSON payload containing information about the TimeGroup that was posted.

Once you have successfully processed the posted time group, respond with HTTP code 200. WiseTime will then let the user know that the time rows have successfully been posted.

Responding any 4xx HTTP code except 408 will tell WiseTime Connect that you are unable to accept this time group. The time group will be unposted in WiseTime, and the user will be shown an error indicator for the relevant time rows.

If you respond with any other HTTP code, WiseTime Connect will retry posting the time group to your webhook a number of times before eventually giving up. WiseTime will then unpost the time, and let the user know that the time rows couldn’t be posted. The user will be able to retry posting the time group again.

Here’s a sample TimeGroup JSON payload:

{
  "callerKey": "80&1f1$b9fd1^",
  "groupId": "5bf7dc15c815720001c55b82",
  "description": "Prepare API service for deployment",
  "totalDurationSecs": 468,
  "groupName": "API Deloyment",
  "narrativeType": "NARRATIVE_AND_TIME_ROW_ACTIVITY_DESCRIPTIONS",
  "tags": [
    {
      "name": "3342",
      "path": "/jira",
      "description": "Deploy API to production"
    }
  ],
  "timeRows": [
    {
      "activity": "Code",
      "description": "deployment.yaml - Visual Studio Code",
      "activityHour": 2018112214,
      "firstObservedInHour" : 9,
      "durationSecs": 168,
      "submittedDate": 20181123105324612,
      "modifier": "",
      "source": "WT_DESKTOP"
    },
    {
      "activity": "jetbrains-idea",
      "description": "api-server master - Main.java - IntelliJ IDEA",
      "activityHour": 2018112214,
      "firstObservedInHour" : 9,
      "durationSecs": 120,
      "submittedDate": 20181123105324612,
      "modifier": "",
      "source": "WT_DESKTOP"
    },
    {
      "activity": "Code",
      "description": "ingress.yaml - Visual Studio Code",
      "activityHour": 2018112214,
      "firstObservedInHour" : 10,
      "durationSecs": 60,
      "submittedDate": 20181123105324612,
      "modifier": "",
      "source": "WT_DESKTOP"
    }
  ],
  "user": {
    "name": "Jane Dev",
    "email": "jane.dev@email.io",
    "externalId": "janed",
    "businessRole": "Software Engineer",
    "experienceWeightingPercent": 100
  },
  "originatingUser": {
    "name": "John Dev",
    "email": "john.dev@email.io",
    "externalId": "johnd",
    "businessRole": "Software Engineer",
    "experienceWeightingPercent": 100
  },
  "durationSplitStrategy": "DIVIDE_BETWEEN_TAGS"
}

TimeGroup Properties

callerKey

Type: String, optional

When you register a webhook, you can specify a caller key that you would like WiseTime to use when it calling the webhook. You can then use this field to authenticate that the request comes from WiseTime. This field will be blank if you didn’t specify a caller key when registering the webhook.

 

groupId

Type: String, required

A string that uniquely identifies the posted TimeGroup.

 

description

Type: String, optional

User description for this time group. This may be blank if the user did not provide a narrative when posting their time.

 

totalDurationSecs

Type: Integer, required

By default this is the sum of the time log durations in seconds. It may have been edited by user before posting. To calculate the unmodified total duration, add the items from the timeRows array.

 

groupName

Type: String, optional

When a group name is created in the WiseTime console, it is assigned the name of the colour that is shown for the group in the user interface. For example, Blue Group. The user can rename the group to provide a more descriptive name. This field may be blank in the case that the user has selected a group of rows and posted that time without explicitly creating a group. It is therefore an optional field.

 

narrativeType

Type: String enum value, required

The possible values are:

  • NARRATIVE_AND_TIME_ROW_ACTIVITY_DESCRIPTIONS
  • NARRATIVE_ONLY

The user may request that the time row activity information be ignored by the web hook receiver. In the usual case, the default narrative type is NARRATIVE_AND_TIME_ROW_ACTIVITY_DESCRIPTIONS.

 

tags

Type: Array of Tags, required, possibly empty

An array of tags that were assigned to the time group. An empty array will be sent if there were no assigned tags.

 

timeRows

Type: Array of TimeRows, required, non-empty

Activity time rows posted with the group. There will always be at least one time row posted.

 

user

Type: User object, required

Information about the user who posted the time group. If the posted time is associated to a User, then this field will be populated with information about the user who is the recipient of the associated time.

 

originatingUser

Type: User object, optional

Only relevant if the posted time was associated to a User, this field contains information about the user that posted the time.

 

durationSplitStrategy

Type: String enum value, optional

The possible values are:

  • DIVIDE_BETWEEN_TAGS
  • WHOLE_DURATION_TO_EACH_TAG

Only relevant when the group has more than one tag. This instructs the endpoint whether time should be divided between tags (default behaviour), or if WHOLE_DURATION_TO_EACH_TAG is set, the webhook receiver is asked to post the full/undivided time to each of the tags listed in the tags array.

 

TimeRow Properties

activity

Type: String, required

The activity performed, e.g. “Meeting”, “Microsoft Word”.

 

description

Type: String, required

A description of the activity, e.g. the filename of a wordprocessor document being worked on.

 

activityHour

Type: Integer, required

The date and hour, in UTC, during which the activity was performed, in the following format: yyyyMMddhh.

 

firstObservedInHour

Type: Integer, required

The firstObservedInHour represents the minute in the activityHour when the activity was first observed. It will be an integer value between 0 and 59.

 

durationSecs

Type: Integer, required

The duration of the activity, in seconds.

 

submittedDate

Type: Long integer, required

The time at which the activity was submitted by the user, in UTC. The format for this field is yyyyMMddHHmmSSsss.

 

modifier

Type: String, optional

A modifier for the time row. Modifiers can be selected by the user when posting time, and can be any string value that makes sense to the connected system when posted. For example, a law firm might configure activity codes for the various activities that they have set up in their case management system, so that they can charge meetings and court appearances at different rates.

 

source

Type: String enum value, required

The possible values are:

  • WT_DESKTOP
  • USER_MANUAL_TIME

This field describes the origin of the time row. Time logs can either come from the desktop client (WT_DESKTOP) or be created manually by the user (USER_MANUAL_TIME).

 

Tag Properties

name

Type: String, required

The name of the tag.

 

path

Type: String, required

The folder path of the tag, e.g. /path/to/tag/.

 

description

Type: String, optional

The text that is displayed to the user next to the tag name in the user interface. For example, this could take the form of a matter description or a project name.

 

User Properties

name

Type: String, required

The name of the user.

 

email

Type: String, required

The user’s email address.

 

externalId

Type: String, optional

The ID that the connector should use to refer to the user when talking to the system being integrated with WiseTime. This is set through the user’s team membership.

 

businessRole

Type: String, optional

The user’s role, set through their team membership.

 

experienceWeightingPercent

Type: Integer, required

Experience rating assigned to the user. This is a percentage value, between 0 and 100. You can use this value to apply a multiplier to the total posted time duration before sending it to the connected system. For example, you may want to send 20 minutes instead of 40 minutes for a junior employee whose experience rating is 50%.