Webhooks based on Zapier's now-deprecated REST Hooks specification. You can use these to receive a postback to a custom URL when certain events happen in VSCO Workspace. Much like an Automation Web Request Action, these webhooks will trigger when the event occurs. However, for security reasons, only the targetId will be provided, which you'll then use to fetch the current version of the entity via the API.
openapi: 3.0.0
info:
title: VSCO Workspace Brands Rest Hooks API
termsOfService: https://terms-of-service.vsco.page/
description: This API is for interacting with a single Studio using <a href="https://workspace.vsco.co/settings/api" target="_blank">an API Key</a>.
contact:
name: VSCO Workspace Support
url: https://help.workspace.vsco.co/
email: workspace-support@vsco.co
version: v2.0.0
x-logo:
url: https://workspace.vsco.co/static/Images/Public/Logo.Black.vsco.svg
altText: VSCO Workspace
servers:
- url: https://tave.io/v2
description: Legacy Táve API production environment
- url: https://workspace.vsco.co/api/v2
description: Workspace API production environment
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Rest Hooks
description: Webhooks based on <a href="https://zapier.com/engineering/introducing-resthooksorg/" target="_blank">Zapier's now-deprecated REST Hooks specification</a>.<br> <br> You can use these to receive a postback to a custom URL when certain events happen in VSCO Workspace.<br> <br> Much like an Automation Web Request Action, these webhooks will trigger when the event occurs. However, for security reasons, only the <code>targetId</code> will be provided, which you'll then use to fetch the current version of the entity via the API.
paths:
/rest-hook:
get:
summary: List Rest Hooks
operationId: listResourceRestHook
x-entity: RestHook
tags:
- Rest Hooks
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/includeHidden'
- name: sortBy
in: query
description: Sort items in the collection by the given property.
schema:
title: Sort objects by properties
type: string
anyOf:
- title: id
enum:
- id
- id asc
- id desc
- title: modified
enum:
- modified
- modified asc
- modified desc
- title: created
enum:
- created
- created asc
- created desc
default: id
responses:
'200':
description: RestHook list response.
content:
application/json:
schema:
$ref: '#/components/schemas/RestHookCollection'
'400':
$ref: '#/components/responses/validationError'
'429':
$ref: '#/components/responses/tooManyRequestsError'
post:
summary: Create a RestHook subscription.
operationId: createResourceRestHook
tags:
- Rest Hooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RestHook'
responses:
'201':
description: RestHook creation response.
content:
application/json:
schema:
$ref: '#/components/schemas/RestHook'
'400':
$ref: '#/components/responses/validationError'
'429':
$ref: '#/components/responses/tooManyRequestsError'
/rest-hook/{id}:
get:
summary: Get a specific Rest Hook
operationId: getResourceRestHook
tags:
- Rest Hooks
parameters:
- $ref: '#/components/parameters/idInPath'
responses:
'200':
description: Fetch a specific RestHook entity.
content:
application/json:
schema:
$ref: '#/components/schemas/RestHook'
'400':
$ref: '#/components/responses/validationError'
'429':
$ref: '#/components/responses/tooManyRequestsError'
put:
summary: Update a specific RestHook.
operationId: updateResourceRestHook
tags:
- Rest Hooks
parameters:
- $ref: '#/components/parameters/idInPath'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RestHook'
responses:
'200':
description: RestHook response.
content:
application/json:
schema:
$ref: '#/components/schemas/RestHook'
'400':
$ref: '#/components/responses/validationError'
'429':
$ref: '#/components/responses/tooManyRequestsError'
delete:
summary: Unsubscribe from and delete a RestHook.
operationId: deleteResourceRestHook
tags:
- Rest Hooks
parameters:
- $ref: '#/components/parameters/idInPath'
responses:
'204':
$ref: '#/components/responses/deleteSuccess'
'400':
$ref: '#/components/responses/validationError'
'429':
$ref: '#/components/responses/tooManyRequestsError'
components:
schemas:
Link:
title: Hypermedia Link Relationship
description: 'The target URL indicated in the `href` property is related to the
current resource according to the defined semantics of the link
property name.'
type: object
required:
- href
properties:
href:
description: The hypertext reference to the API resource at tave.io.
type: string
format: uri
managerHref:
description: The URL to this item inside the Manager application at workspace.vsco.co.
type: string
format: uri
clientHref:
description: The URL to this item in Client Access, if available.
type: string
format: uri
RestHook:
title: Rest Hook
description: http://resthooks.org/
type: object
required:
- event
- url
properties:
links:
$ref: '#/components/schemas/Links'
id:
$ref: '#/components/schemas/Id'
created:
$ref: '#/components/schemas/ServerTimestamp'
modified:
$ref: '#/components/schemas/ServerTimestamp'
hidden:
$ref: '#/components/schemas/IsHidden'
event:
type: string
enum:
- contact.created
- job.created
- order.booked
- payment.created
limitTo:
type: object
nullable: true
default: null
properties:
contactKinds:
description: Only available for contact.created events
type: array
items:
type: string
enum:
- person
- company
- location
jobTypes:
description: Not available on contact.created events
type: array
items:
$ref: '#/components/schemas/Id'
brands:
type: array
items:
$ref: '#/components/schemas/Id'
webLead:
description: Only available for job.created events
type: boolean
url:
type: string
format: uri
Links:
title: Link Relationships
description: 'Each property defines a hypertext link relationship as indicated by a
link object or array of link objects. The target URL of each hypertext
link relationship is related to the current resource according to the
defined semantics of the link relationship property name.'
readOnly: true
required:
- self
type: object
example: "\"self\": {\n \"href\": \"https://example.com/object-endpoint/03c41781-f06f-4402-a5d9-1c30ccb4db29\",\n \"title\": \"Example Link Relationship\",\n \"type\": \"application/json\",\n}"
properties:
self:
allOf:
- title: Self
description: The target URL is the current resource's own location.
- $ref: '#/components/schemas/Link'
RestHookCollection:
allOf:
- properties:
type:
enum:
- resthook-collection
items:
title: Rest Hooks
type: array
items:
$ref: '#/components/schemas/RestHook'
- $ref: '#/components/schemas/List'
IsHidden:
title: Hidden attribute
description: Whether or not the object is hidden.
type: boolean
example: false
readOnly: true
ErrorValidation:
description: A validation error.
type: object
properties:
type:
description: A namespace URI uniquely identifying the error type.
type: string
enum:
- validation-error
title:
description: A short description of the error encountered.
type: string
example: Validation Error
detail:
description: Breakdown of what fields valid validation and why
type: object
status:
description: The HTTP status code associated with this error.
type: integer
example: 400
Id:
title: Entity Identifier
description: A lowercase [ULID](https://github.com/ulid/spec) entity identifier
type: string
format: ulid
example: 01h35ccwymj5ctckp8px1azhg6
readOnly: true
ResourceType:
title: Resource Type
description: The type of resource represented.
type: string
example: resource-type
Error:
description: An error.
type: object
properties:
type:
description: A namespace URI uniquely identifying the error type.
type: string
enum:
- unknown
- quota-limit
- not-implemented
title:
description: A short description of the error encountered.
type: string
example: Bad Request
detail:
description: A longer description of of the error encountered.
type: string
example: There was a problem with your request. Please see `info` for more information.
status:
description: The HTTP status code associated with this error.
type: integer
example: 400
ServerTimestamp:
title: Server Timestamp
description: A server timestamp (always in UTC)
type: string
format: date-time
readOnly: true
example: '2020-08-01T17:32:32Z'
List:
title: Collection
description: A collection (or list) of resources.
type: object
required:
- type
- items
properties:
meta:
description: Metadata describing the current result set.
type: object
readOnly: true
properties:
currentPage:
description: The current page of results returned.
type: integer
totalPages:
description: 'The total number of pages in the result set. This is affected by
the `pageSize` parameter (`totalItems / pageSize == totalPages`).'
type: integer
totalItems:
description: 'The total number of items in the result set. This may be
affected by active search/filter parameters.'
type: integer
rows:
description: The number of rows returned per page for the current result set.
type: integer
type:
$ref: '#/components/schemas/ResourceType'
items:
description: A collection of resources returned in the current result set.
type: array
items:
type: object
parameters:
pageSize:
name: pageSize
in: query
description: Number of results per page to return in the collection.
schema:
type: integer
minimum: 10
maximum: 100
default: 100
idInPath:
name: id
in: path
description: ULID to perform an action on.
schema:
$ref: '#/components/schemas/Id'
page:
name: page
in: query
description: The page of results to return.
schema:
type: integer
default: 1
minimum: 1
includeHidden:
name: includeHidden
in: query
description: Include objects that have been hidden
schema:
type: boolean
default: false
example: false
responses:
validationError:
description: 'Validation error response. Check the `info.errors` property in the
response for more details.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorValidation'
tooManyRequestsError:
description: Exceeded request quota, see Retry-After header
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
deleteSuccess:
description: The resource was successfully deleted.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
BearerAuth:
type: http
scheme: bearer
x-tagGroups:
- name: Jobs & Contacts
tags:
- Jobs
- Job Contacts
- Job Worksheets
- Contacts
- Events
- Files
- Galleries
- Notes
- Orders
- Payment
- name: Studio Settings
tags:
- Studio
- Brands
- Custom Fields
- Discounts
- Discount Types
- Event Types
- File Types
- Job Closed Reasons
- Job Roles
- Job Types
- Lead Sources
- Lead Statuses
- Payment Methods
- Products
- Product Types
- Profit Centers
- Tax Groups
- Tax Rates
- Timezones
- Users
- name: API Resources
tags:
- Rest Hooks