Documentation (2024.2 Enterprise)

# Hook

Hooks can be used to notify external hook services about Helix TeamHub related events.

- Attributes
- Operations
  - `GET /hooks`
  - `GET /hooks/:id`
  - `POST /hooks`
  - `PUT /hooks/:id`
  - `DELETE /hooks/:id`
  - `GET /hooks/count`
  - `GET /projects/:project_id/hooks`
  - `GET /projects/:project_id/hooks/:id`
  - `POST /projects/:project_id/hooks`
  - `PUT /projects/:project_id/hooks/:id`
  - `DELETE /projects/:project_id/hooks/:id`
  - `GET /projects/:project_id/hooks/count`
  - `GET /projects/:project_id/repositories/:repository_id/hooks`
  - `GET /projects/:project_id/repositories/:repository_id/hooks/:id`
  - `POST /projects/:project_id/repositories/:repository_id/hooks`
  - `PUT /projects/:project_id/repositories/:repository_id/hooks/:id`
  - `DELETE /projects/:project_id/repositories/:repository_id/hooks/:id`
  - `GET /projects/:project_id/repositories/:repository_id/hooks/count`

Forward slash characters in `:repository_id` must be encoded with `%2F`

## Attributes

### id

A URL-friendly identifier for the hook.

- Type: `string`
- Unique: `true`

### hook_service

The identifier of the Hook service. Full object can be expanded with GET requests.

- Type: `string` / `object`

### events

An array of events to hook into.

- Type: `array`

### config

An object containing the hook service configurations.

- Type: `object`

### hookable_type

A type of `hookable` object. Possible values are `company`, `project` and `repository`.

- Type: `string`

### hookable

A hookable object.

- Type: `object`

## Operations

### GET /hooks

Returns all hooks for a company, with optional limit and offset parameters, as a metadata-results object.

### GET /hooks/:id

Returns a single hook.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/hooks/578f5eea646576644d00000a

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-07-10T12:39:08Z",
      "id": "578f5eea646576644d00000a",
      "created_at": "2013-07-05T12:44:01Z",
      "updated_at": "2013-07-09T07:08:17Z",
      "hook_service": {
        "id": "webhook"
      },
      "events": [
        "project"
      ],
      "config": { "url": "http://requestb.in/foo" },
      "hookable_type": "company",
      "hookable": {
        "id": "hth",
        "uuid": "f38c3579-d43f-4f7e-b74a-b15d1e32ef46"
      }
    }

### POST /hooks

Creates a new hook for a company. Returns the created hook object.

#### Example Request

    curl -X POST \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "hook_service": "webhook", "events": ["project"], "config": { "url": "http://requestb.in/foo" } }' \
      https://helixteamhub.cloud/api/hooks

#### Example Response

    {
      "api_status": 201,
      "api_timestamp": "2013-07-10T13:17:27Z",
      "id": "578f5eea646576644d00000a",
      "created_at": "2013-07-10T13:17:27Z",
      "updated_at": "2013-07-10T13:17:27Z",
      "hook_service": {
        "id": "webhook"
      },
      "events": [
        "project"
      ],
      "config": { "token": "http://requestb.in/foo" },
      "hookable_type": "company",
      "hookable": {
        "id": "hth",
        "uuid": "f38c3579-d43f-4f7e-b74a-b15d1e32ef46"
      }
    }

### PUT /hooks/:id

Updates a hook for a company. Returns the updated hook object.

#### Example Request

    curl -X PUT \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "hook_service": "webhook", "events": ["project"], "config": {"token": "http://requestb.in/bar"} }' \
      https://helixteamhub.cloud/api/hooks/578f5eea646576644d00000a

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-07-10T15:28:29Z",
      "id": "578f5eea646576644d00000a",
      "created_at": "2013-07-10T15:26:00Z",
      "updated_at": "2013-07-10T15:28:29Z",
      "hook_service": {
        "id": "webhook"
      },
      "events": [
        "project"
      ],
      "config": { "token": "http://requestb.in/bar" },
      "hookable_type": "company",
      "hookable": {
        "id": "hth",
        "uuid": "f38c3579-d43f-4f7e-b74a-b15d1e32ef46"
      }
    }

### DELETE /hooks/:id

Deletes a hook from a company. Return the deleted hook object.

#### Example Request

    curl -X DELETE \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/hooks/578f5eea646576644d00000a

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-07-10T13:19:48Z",
      "id": "578f5eea646576644d00000a",
      "created_at": "2013-07-10T13:17:27Z",
      "updated_at": "2013-07-10T13:17:27Z",
      "hook_service": {
        "id": "webhook"
      },
      "events": [
        "project"
      ],
      "config": { "token": "http://requestb.in/foo" },
      "hookable_type": "company",
      "hookable": {
        "id": "hth",
        "uuid": "f38c3579-d43f-4f7e-b74a-b15d1e32ef46"
      }
    }

### GET /hooks/count

Returns an object containing the amounts of total, active, and inactive hooks in the company.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/hooks/count

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2016-07-26T11:59:44Z",
      "count": 2,
      "active": 2,
      "inactive": 0
    }

### GET /projects/:project_id/hooks

Returns all hooks for a project, with optional limit and offset parameters, as a metadata-results object.

### GET /projects/:project_id/hooks/:id

Returns a single hook.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/projects/luotsi/hooks/51dd5ee71cf35944de000004

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-07-10T12:39:08Z",
      "id": "51dd5ee71cf35944de000004",
      "created_at": "2013-07-05T12:44:01Z",
      "updated_at": "2013-07-09T07:08:17Z",
      "hook_service": {
        "id": "webhook"
      },
      "events": [
        "repository"
      ],
      "config": { "url": "http://requestb.in/foo" },
      "hookable_type": "project",
      "hookable": {
        "id": "luotsi",
        "uuid": "a671a3bb-edb9-45f7-aa71-f3be44a075c2"
      }
    }

### POST /projects/:project_id/hooks

Creates a new hook for a project. Returns the created hook object.

#### Example Request

    curl -X POST \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "hook_service": "webhook", "events": ["repository"], "config": { "url": "http://requestb.in/foo" } }' \
      https://helixteamhub.cloud/api/projects/luotsi/hooks

#### Example Response

    {
      "api_status": 201,
      "api_timestamp": "2013-07-10T13:17:27Z",
      "id": "51dd5ee71cf35944de000004",
      "created_at": "2013-07-10T13:17:27Z",
      "updated_at": "2013-07-10T13:17:27Z",
      "hook_service": {
        "id": "webhook"
      },
      "events": [
        "repository"
      ],
      "config": { "token": "http://requestb.in/foo" },
      "hookable_type": "project",
      "hookable": {
        "id": "luotsi",
        "uuid": "a671a3bb-edb9-45f7-aa71-f3be44a075c2"
      }
    }

### PUT /projects/:project_id/hooks/:id

Updates a hook for a project. Returns the updated hook object.

#### Example Request

    curl -X PUT \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "hook_service": "webhook", "events": ["repository"], "config": {"token": "http://requestb.in/bar"} }' \
      https://helixteamhub.cloud/api/projects/luotsi/hooks/51dd5ee71cf35944de000004

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-07-10T15:28:29Z",
      "id": "51dd5ee71cf35944de000004",
      "created_at": "2013-07-10T15:26:00Z",
      "updated_at": "2013-07-10T15:28:29Z",
      "hook_service": {
        "id": "webhook"
      },
      "events": [
        "repository"
      ],
      "config": { "token": "http://requestb.in/bar" },
      "hookable_type": "project",
      "hookable": {
        "id": "luotsi",
        "uuid": "a671a3bb-edb9-45f7-aa71-f3be44a075c2"
      }
    }

### DELETE /projects/:project_id/hooks/:id

Deletes a hook from a project. Return the deleted hook object.

#### Example Request

    curl -X DELETE \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/projects/luotsi/hooks/51dd5ee71cf35944de000004

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-07-10T13:19:48Z",
      "id": "51dd5ee71cf35944de000004",
      "created_at": "2013-07-10T13:17:27Z",
      "updated_at": "2013-07-10T13:17:27Z",
      "hook_service": {
        "id": "webhook"
      },
      "events": [
        "repository"
      ],
      "config": { "token": "http://requestb.in/foo" },
      "hookable_type": "project",
      "hookable": {
        "id": "luotsi",
        "uuid": "a671a3bb-edb9-45f7-aa71-f3be44a075c2"
      }
    }

### GET /projects/:project_id/hooks/count

Returns an object containing the amounts of total, active, and inactive hooks in the project.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/projects/luotsi/hooks/count

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2016-07-26T12:02:42Z",
      "count": 2,
      "active": 2,
      "inactive": 0
    }

### GET /projects/:project_id/repositories/:repository_id/hooks

Returns all hooks for a repository, with optional limit and offset parameters, as a metadata-results object.

### GET /projects/:project_id/repositories/:repository_id/hooks/:id

Returns a single hook.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/projects/luotsi/repositories/chef/hooks/51dd5ee71cf35944de000004

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-07-10T12:39:08Z",
      "id": "51dd5ee71cf35944de000004",
      "created_at": "2013-07-05T12:44:01Z",
      "updated_at": "2013-07-09T07:08:17Z",
      "hook_service": {
        "id": "flowdock"
      },
      "events": [
        "push"
      ],
      "config": { "token": "abc" },
      "hookable_type": "repository",
      "hookable": {
        "id": "chef",
        "uuid": "62c5505f-75da-41ed-bc04-de43405d22b1"
      }
    }

### POST /projects/:project_id/repositories/:repository_id/hooks

Creates a new hook for a repository. Returns the created hook object.

#### Example Request

    curl -X POST \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "hook_service": "flowdock", "events": ["push"], "config": {"token": "abc"} }' \
      https://helixteamhub.cloud/api/projects/luotsi/repositories/chef/hooks

#### Example Response

    {
      "api_status": 201,
      "api_timestamp": "2013-07-10T13:17:27Z",
      "id": "51dd5ee71cf35944de000004",
      "created_at": "2013-07-10T13:17:27Z",
      "updated_at": "2013-07-10T13:17:27Z",
      "hook_service": {
        "id": "flowdock"
      },
      "events": [
        "push"
      ],
      "config": {"token":"abc"},
      "hookable_type": "repository",
      "hookable": {
        "id": "chef",
        "uuid": "62c5505f-75da-41ed-bc04-de43405d22b1"
      }
    }

### PUT /projects/:project_id/repositories/:repository_id/hooks/:id

Updates a hook for a repository. Returns the updated hook object.

#### Example Request

    curl -X PUT \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "hook_service": "flowdock", "events": ["push"], "config": {"token": "foobar"} }' \
      https://helixteamhub.cloud/api/projects/luotsi/repositories/chef/hooks/51dd5ee71cf35944de000004

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-07-10T15:28:29Z",
      "id": "51dd5ee71cf35944de000004",
      "created_at": "2013-07-10T15:26:00Z",
      "updated_at": "2013-07-10T15:28:29Z",
      "hook_service": {
        "id": "flowdock"
      },
      "events": [
        "push"
      ],
      "config": {"token":"foobar"},
      "hookable_type": "repository",
      "hookable": {
        "id": "chef",
        "uuid": "62c5505f-75da-41ed-bc04-de43405d22b1"
      }
    }

### DELETE /projects/:project_id/repositories/:repository_id/hooks/:id

Deletes a hook from a repository. Return the deleted hook object.

#### Example Request

    curl -X DELETE \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/projects/luotsi/repositories/chef/hooks/51dd5ee71cf35944de000004

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-07-10T13:19:48Z",
      "id": "51dd5ee71cf35944de000004",
      "created_at": "2013-07-10T13:17:27Z",
      "updated_at": "2013-07-10T13:17:27Z",
      "hook_service": {
        "id": "flowdock"
      },
      "events": [
        "push"
      ],
      "config": {"token":"abc"},
      "hookable_type": "repository",
      "hookable": {
        "id": "chef",
        "uuid": "62c5505f-75da-41ed-bc04-de43405d22b1"
      }
    }

### GET /projects/:project_id/repositories/:repository_id/hooks/count

Returns an object containing the amounts of total, active, and inactive hooks in the repository.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/projects/luotsi/repositories/chef/hooks/count

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2016-07-26T12:05:14Z",
      "count": 2,
      "active": 2,
      "inactive": 0
    }

Your search for returned results

Your search for returned results