Range integrates with other software to create suggested items for users to
add to their check-ins. If you would like to create suggestions from tools not currently integrated with Range, you can set up an incoming webhook to programmatically create suggestions.
Note: Workspaces can be configured to restrict who can create webhooks. If you do not have access please talk reach out to us or talk to your administrator.
Basic Flow
In general suggestions are created that reflect state changes that indicate work has happened: for example, a document was edited, a file was created, an issue opened, or a case closed.
Your integration can issue requests to the webhook whenever a state change happens that should trigger a suggestion. You should consider how suggestions should be de-duplicated and why they are being shown to the user.
The suggestion payload should be POSTed as JSON to the webhook endpoint issued via your workspace's integration settings (under Custom Range integrations).
{
"email_hash": "462cdb844946306eb3a172a2274d91ec23897961",
"is_future": true,
"reason": "ASSIGNED",
"dedupe_strategy": "UPSERT_PENDING",
"attachment": {
"source_id": "12345abc",
"provider": "oncall",
"provider_name": "ACME Oncall Tool",
"html_url": "https://oncall.acme.corp/rotation/12345abc",
"name": "Primary on call for ACME backend",
"type": "LINK"
}
}
The payload fields will be described in detail below.
Suggestion Assignment
The incoming webhook can assign suggestions to users in two ways via their Range user id or via a hash of their email. You can find user id's by looking at the URL of their profile, but for most people the email_hash approach will be easier.
// pseudo code
sha1("bob@acme.corp")
# bash
echo -n "bob@acme.corp" | shasum
De-duplication
In order to avoid duplicates, Range de-duplicates suggestions based on the suggestion's source_id
and a dedupe_strategy
. The deduplication strategy can be one of the following:
UNIQUE
- Only one suggestion will ever be created, even if the suggestion has been published as part of an check-in.
UNIQUE_USER
- As UNIQUE
but one per user.
UNIQUE_PENDING
- A suggestion will only be created if there isn't already a suggestion waiting to be published. If the user dismisses the suggestion, a new one won't be added for four hours.
UPSERT_PENDING
- If an unpublished suggestion already exists, it will be updated with the state from the latest request. This is the most commonly used strategy.
Reasons
Each suggestion can have a reason as to why it is being shown to the user. This is generally a verb that represents the action that created the suggestion. A user may see the same attachment multiple times, with different reasons. For example, on Monday they may open a pull request, and then merge it on Tuesday.
Our current list of reasons is as follows:
ADDED
EDITED
COMMENTED
CLOSED
CREATED
OPENED
STATUS_UPDATED
REVIEWED
RESOLVED
MERGED
COMPLETED
ASSIGNED
ATTENDED
CHANGED
Contact us if you need more verbs.
Attachments
The main content of a suggestion is an "attachment", it represents an artifact that may be included in suggestions for multiple users. The attachment's source_id
should be globally unique to a provider
. For example, if I edit a doc and you comment on a doc, they should both reference the same attachment but with different "reasons". But pull request #101 in acme-corp/widgets should be disambiguated from PR #101 in acme-corp/marketing-site.
An attachment can represent multiple types, and there optional properties associated with certain types.
All date fields should be in UTC ISO8601 (2006-01-02T15:04:05.999Z
) as compatible with JavaScript's toISOString()
.
Core fields:
source_id
unique identifier for the attachment. Used to de-duplicate suggestions.provider
lowercase-alphanumeric identifier for your custom provider. e.g. "figma".provider_name
user visible description of the provider, e.g. "Figma".type
the attachment type, see below.name
name for the suggestion, a file name, pull request title, or event name.html_url
URL to link to for people to access the attachment.
The attachment's primary key can be considered a tuple of (source_id
, provider
).
Additional fields:
description
(optional) descriptive text for the attachment. Limited to 255 chars.parent_name
name for the parent of the attachment, e.g. a folder, project, repo.parent_html_url
(optional) URL to link people to access the parent
Type: LINK
No additional properties.
Type: FILE
date_created
date_modified
file_format
file extension, e.g. jpg, png, zipfile_type
user visible description of the file, e.g. "Figma Drawing"
Type: EVENT
start_date
(optional)end_date
(optional)location
(optional)num_attendees
(optional)session_identifier
Type: CODE_CHANGE
change_id
string used when displaying the change change_label
prefix used when displaying change id. e.g. PR #123
, cl/123
change_state
e.g. merged, opened, closed
Type: ISSUE
issue_id
string used when displaying the issue
e.g. opened, closed, duplicate
issue_stateissue_label
prefix used when displaying issue ids. e.g. Issue #455
, b/455
date_opened
(optional)date_closed
(optional)
Type: TASK
task_state
e.g. opened, closed, complete, donedate_completed
(optional)
Sample Code
This gist contains a simple example for how to post a simple link to the incoming webhook using a node script.
We also have a self-hosted GitHub integration that may be a useful reference.
If there are entity types and fields that you would like us to consider, please get in touch.