Hooks API Documentation


BaseUrl
https://hooks.taskcluster.net/v1

Hooks are a mechanism for creating tasks in response to events.

Hooks are identified with a hookGroupId and a hookId.

When an event occurs, the resulting task is automatically created. The task is created using the scope assume:hook-id:<hookGroupId>/<hookId>, which must have scopes to make the createTask call, including satisfying all scopes in task.scopes. The new task has a taskGroupId equal to its taskId, as is the convention for decision tasks.

Hooks can have a "schedule" indicating specific times that new tasks should be created. Each schedule is in a simple cron format, per https://www.npmjs.com/package/cron-parser. For example:

  • ['0 0 1 * * *'] -- daily at 1:00 UTC
  • ['0 0 9,21 * * 1-5', '0 0 12 * * 0,6'] -- weekdays at 9:00 and 21:00 UTC, weekends at noon

The task definition is used as a JSON-e template, with a context depending on how it is fired. See /docs/reference/core/taskcluster-hooks/docs/firing-hooks for more information.

Functions

Using the APIs
SignatureSummary
ping() : voidPing Server
listHookGroups() : resultList hook groups
listHooks(hookGroupId) : resultList hooks in a given group
hook(hookGroupId, hookId) : resultGet hook definition
getHookStatus(hookGroupId, hookId) : resultGet hook status
createHook(hookGroupId, hookId, payload) : resultCreate a hook
updateHook(hookGroupId, hookId, payload) : resultUpdate a hook
removeHook(hookGroupId, hookId) : voidDelete a hook
triggerHook(hookGroupId, hookId, payload) : resultTrigger a hook
getTriggerToken(hookGroupId, hookId) : resultGet a trigger token
resetTriggerToken(hookGroupId, hookId) : resultReset a trigger token
triggerHookWithToken(hookGroupId, hookId, token, payload) : resultTrigger a hook with a token

Ping Server

Method
get
Route
/ping
Signature
ping() : void
Stability
stable

Respond without doing anything. This endpoint is used to check that the service is up.



List hook groups

Method
get
Route
/hooks
Signature
listHookGroups() : result
Stability
stable

This endpoint will return a list of all hook groups with at least one hook.

Response

Hook groups (source)

List of hookGroupIds.

groupsArray of
string


List hooks in a given group

Method
get
Route
/hooks/<hookGroupId>
Signature
listHooks(hookGroupId) : result
Stability
stable

This endpoint will return a list of all the hook definitions within a given hook group.

Response

Hook list (source)

List of hooks

hooksArray of
hookGroupIdstring[1:64]^([a-zA-Z0-9-_]*)$
hookIdstring[1:64]^([a-zA-Z0-9-_/]*)$
metadataObject of
namestring[0:255]

Human readable name of the hook

descriptionstring[0:32768]

Long-form of the hook's purpose and behavior

ownerstring[0:255]

Email of the person or group responsible for this hook.

emailOnErrorboolean
default: true

Whether to email the owner on an error creating the task.

schedule

Definition of the times at which a hook will result in creation of a task. If several patterns are specified, tasks will be created at any time specified by one or more patterns. Note that tasks may not be created at exactly the time specified. {$ref: "schedule.json#"}

taskObject of

Template for the task definition. This is rendered using JSON-e as described in firing hooks to produce a task definition that is submitted to the Queue service.

Anything ¯\_(ツ)_/¯
triggerSchemaObject of
Anything ¯\_(ツ)_/¯


Get hook definition

Method
get
Route
/hooks/<hookGroupId>/<hookId>
Signature
hook(hookGroupId, hookId) : result
Stability
stable

This endpoint will return the hook definition for the given hookGroupId and hookId.

Response

Hook definition (source)

Definition of a hook that will create tasks when defined events occur.

hookGroupIdstring[1:64]^([a-zA-Z0-9-_]*)$
hookIdstring[1:64]^([a-zA-Z0-9-_/]*)$
metadataObject of
namestring[0:255]

Human readable name of the hook

descriptionstring[0:32768]

Long-form of the hook's purpose and behavior

ownerstring[0:255]

Email of the person or group responsible for this hook.

emailOnErrorboolean
default: true

Whether to email the owner on an error creating the task.

schedule

Definition of the times at which a hook will result in creation of a task. If several patterns are specified, tasks will be created at any time specified by one or more patterns. Note that tasks may not be created at exactly the time specified. {$ref: "schedule.json#"}

taskObject of

Template for the task definition. This is rendered using JSON-e as described in firing hooks to produce a task definition that is submitted to the Queue service.

Anything ¯\_(ツ)_/¯
triggerSchemaObject of
Anything ¯\_(ツ)_/¯


Get hook status

Method
get
Route
/hooks/<hookGroupId>/<hookId>/status
Signature
getHookStatus(hookGroupId, hookId) : result
Stability
stable

This endpoint will return the current status of the hook. This represents a snapshot in time and may vary from one call to the next.

Response

Hook status response (source)

A snapshot of the current status of a hook.

lastFireOne of

Information about the last time this hook fired. This property is only present if the hook has fired at least once.

Successful FireObject of

Information about a successful firing of the hook

resultstring
  • success
taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

The task created

timestringdate-time

The time the task was created. This will not necessarily match task.created.

Failed FireObject of

Information about an unsuccessful firing of the hook

resultstring
  • error
errorObject of

The error that occurred when firing the task. This is typically, but not always, an API error message.

Anything ¯\_(ツ)_/¯
timestringdate-time

The time the task was created. This will not necessarily match task.created.

No FireObject of

Information about no firing of the hook (e.g., a new hook)

resultstring
  • no-fire
nextScheduledDatestringdate-time

The next time this hook's task is scheduled to be created. This property is only present if there is a scheduled next time. Some hooks don't have any schedules.



Create a hook

Method
put
Route
/hooks/<hookGroupId>/<hookId>
Scopes
all of
hooks:modify-hook:<hookGroupId>/<hookId> and
assume:hook-id:<hookGroupId>/<hookId>
Signature
createHook(hookGroupId, hookId, payload) : result
Stability
stable

This endpoint will create a new hook.

The caller's credentials must include the role that will be used to create the task. That role must satisfy task.scopes as well as the necessary scopes to add the task to the queue.

Request Payload

Hook creation request (source)

Definition of a hook that can create tasks at defined times.

hookGroupIdstring[1:64]^([a-zA-Z0-9-_]*)$
hookIdstring[1:64]^([a-zA-Z0-9-_/]*)$
metadataObject of
namestring[0:255]

Human readable name of the hook

descriptionstring[0:32768]

Long-form of the hook's purpose and behavior

ownerstring[0:255]

Email of the person or group responsible for this hook.

emailOnErrorboolean
default: true

Whether to email the owner on an error creating the task.

scheduleArray of
default:

Definition of the times at which a hook will result in creation of a task. If several patterns are specified, tasks will be created at any time specified by one or more patterns.

Cron Patternstring

Cron-like specification for when tasks should be created. The pattern is parsed in a UTC context. See cron-parser on npm. Note that tasks may not be created at exactly the time specified.

taskObject of

Template for the task definition. This is rendered using JSON-e as described in firing hooks to produce a task definition that is submitted to the Queue service.

Anything ¯\_(ツ)_/¯
triggerSchemaObject of
default: [object Object]
Anything ¯\_(ツ)_/¯

Response

Hook definition (source)

Definition of a hook that will create tasks when defined events occur.

hookGroupIdstring[1:64]^([a-zA-Z0-9-_]*)$
hookIdstring[1:64]^([a-zA-Z0-9-_/]*)$
metadataObject of
namestring[0:255]

Human readable name of the hook

descriptionstring[0:32768]

Long-form of the hook's purpose and behavior

ownerstring[0:255]

Email of the person or group responsible for this hook.

emailOnErrorboolean
default: true

Whether to email the owner on an error creating the task.

schedule

Definition of the times at which a hook will result in creation of a task. If several patterns are specified, tasks will be created at any time specified by one or more patterns. Note that tasks may not be created at exactly the time specified. {$ref: "schedule.json#"}

taskObject of

Template for the task definition. This is rendered using JSON-e as described in firing hooks to produce a task definition that is submitted to the Queue service.

Anything ¯\_(ツ)_/¯
triggerSchemaObject of
Anything ¯\_(ツ)_/¯


Update a hook

Method
post
Route
/hooks/<hookGroupId>/<hookId>
Scopes
all of
hooks:modify-hook:<hookGroupId>/<hookId> and
assume:hook-id:<hookGroupId>/<hookId>
Signature
updateHook(hookGroupId, hookId, payload) : result
Stability
stable

This endpoint will update an existing hook. All fields except hookGroupId and hookId can be modified.

Request Payload

Hook creation request (source)

Definition of a hook that can create tasks at defined times.

hookGroupIdstring[1:64]^([a-zA-Z0-9-_]*)$
hookIdstring[1:64]^([a-zA-Z0-9-_/]*)$
metadataObject of
namestring[0:255]

Human readable name of the hook

descriptionstring[0:32768]

Long-form of the hook's purpose and behavior

ownerstring[0:255]

Email of the person or group responsible for this hook.

emailOnErrorboolean
default: true

Whether to email the owner on an error creating the task.

scheduleArray of
default:

Definition of the times at which a hook will result in creation of a task. If several patterns are specified, tasks will be created at any time specified by one or more patterns.

Cron Patternstring

Cron-like specification for when tasks should be created. The pattern is parsed in a UTC context. See cron-parser on npm. Note that tasks may not be created at exactly the time specified.

taskObject of

Template for the task definition. This is rendered using JSON-e as described in firing hooks to produce a task definition that is submitted to the Queue service.

Anything ¯\_(ツ)_/¯
triggerSchemaObject of
default: [object Object]
Anything ¯\_(ツ)_/¯

Response

Hook definition (source)

Definition of a hook that will create tasks when defined events occur.

hookGroupIdstring[1:64]^([a-zA-Z0-9-_]*)$
hookIdstring[1:64]^([a-zA-Z0-9-_/]*)$
metadataObject of
namestring[0:255]

Human readable name of the hook

descriptionstring[0:32768]

Long-form of the hook's purpose and behavior

ownerstring[0:255]

Email of the person or group responsible for this hook.

emailOnErrorboolean
default: true

Whether to email the owner on an error creating the task.

schedule

Definition of the times at which a hook will result in creation of a task. If several patterns are specified, tasks will be created at any time specified by one or more patterns. Note that tasks may not be created at exactly the time specified. {$ref: "schedule.json#"}

taskObject of

Template for the task definition. This is rendered using JSON-e as described in firing hooks to produce a task definition that is submitted to the Queue service.

Anything ¯\_(ツ)_/¯
triggerSchemaObject of
Anything ¯\_(ツ)_/¯


Delete a hook

Method
delete
Route
/hooks/<hookGroupId>/<hookId>
Scopes
hooks:modify-hook:<hookGroupId>/<hookId>
Signature
removeHook(hookGroupId, hookId) : void
Stability
stable

This endpoint will remove a hook definition.



Trigger a hook

Method
post
Route
/hooks/<hookGroupId>/<hookId>/trigger
Scopes
hooks:trigger-hook:<hookGroupId>/<hookId>
Signature
triggerHook(hookGroupId, hookId, payload) : result
Stability
stable

This endpoint will trigger the creation of a task from a hook definition.

The HTTP payload must match the hooks triggerSchema. If it does, it is provided as the payload property of the JSON-e context used to render the task template.

Request Payload

Trigger Hook Request (source)

A request to trigger a hook. The payload must be a JSON object, and is used as the context for a JSON-e rendering of the hook's task template, as described in "Firing Hooks".

Anything ¯\_(ツ)_/¯

Response

Task Status Structure (source)

A representation of task status as known by the queue

statusObject of
taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.



Get a trigger token

Method
get
Route
/hooks/<hookGroupId>/<hookId>/token
Scopes
hooks:get-trigger-token:<hookGroupId>/<hookId>
Signature
getTriggerToken(hookGroupId, hookId) : result
Stability
stable

Retrieve a unique secret token for triggering the specified hook. This token can be deactivated with resetTriggerToken.

Response

trigger token response (source)

Secret token for a trigger

tokenstring


Reset a trigger token

Method
post
Route
/hooks/<hookGroupId>/<hookId>/token
Scopes
hooks:reset-trigger-token:<hookGroupId>/<hookId>
Signature
resetTriggerToken(hookGroupId, hookId) : result
Stability
stable

Reset the token for triggering a given hook. This invalidates token that may have been issued via getTriggerToken with a new token.

Response

trigger token response (source)

Secret token for a trigger

tokenstring


Trigger a hook with a token

Method
post
Route
/hooks/<hookGroupId>/<hookId>/trigger/<token>
Signature
triggerHookWithToken(hookGroupId, hookId, token, payload) : result
Stability
stable

This endpoint triggers a defined hook with a valid token.

The HTTP payload must match the hooks triggerSchema. If it does, it is provided as the payload property of the JSON-e context used to render the task template.

Request Payload

Trigger Hook Request (source)

A request to trigger a hook. The payload must be a JSON object, and is used as the context for a JSON-e rendering of the hook's task template, as described in "Firing Hooks".

Anything ¯\_(ツ)_/¯

Response

Task Status Structure (source)

A representation of task status as known by the queue

statusObject of
taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.