Listing private hooks

Function

ListPrivateHooks

This API lists all private hooks of the current account (domain) at the current region.

You can use sort_key and sort_dir as keywords to sort the returned results by creation time (create_time). The number of sort_keys must be the same as that of sort_dirs. Otherwise, error code 400 is returned. If sort_key and sort_dir are not assigned, results are sorted by creation time in descending order by default.
Currently, all hooks are returned. Pagination is not supported.
If there is no private hook, an empty list will be returned.
The specific information returned can be found in ListPrivateHooksResponseBody.

URI

GET /v1/private-hooks

**Table 1** Query Parameters
Parameter	Mandatory	Type	Description
sort_key	No	Array of strings	Sorting field. Only create_time is supported.
sort_dir	No	Array of strings	Specify an ascending or descending order. asc: ascending order desc: descending order

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
Client-Request-Id	Yes	String	Unique request ID. It is specified by a user and is used to locate a request. UUID is recommended.

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
hooks	Array of PrivateHookSummary objects	Private hooks, sorted by creation time in descending order by default.

**Table 4** PrivateHookSummary
Parameter	Type	Description
hook_name	String	Private hook name. The name is unique within its domain (domain_id) and region. It can contain Chinese characters, uppercase and lowercase letters, digits, underscores (_), and hyphens (-). The first character must be a Chinese or English character. It is case sensitive. We recommend users to use a three-part namespace for naming: {custom-hook-name}-{hook application context}-hook.
hook_id	String	Unique ID of a private hook. It is an UUID generated by RFS when a private hook is created. Private hook names are unique only at one specific time, so you can create a private hook named helloWorld and another private hook with the same name after deleting the first one. For parallel development in a team, users may want to ensure that the private hook they operate is the one created by themselves, not the one with the same name created by other teammates after deleting the previous one. Therefore, they can use this ID for strong matching. RFS ensures that the ID of each private hook is different and does not change with updates. If the hook_id value is different from the current private hook ID, error code 400 is returned.
hook_description	String	Description of a private hook. It can be used by customers to identify their own private hooks. You can update the description of the private hook by calling UpdatePrivateHook API.
default_version	String	Private hook default version. The version number follows the Semantic Version and is customized by the user.
configuration	configuration object	Private hook configuration. It can specify the target stack where the private hook takes effect and the behavior of the stack after the private hook verification fails. You can use UpdatePrivateHook API to update private hook configuration.
create_time	String	Time when a private hook is created. It uses a UTC (YYYY-MM-DDTHH:mm:ss.SSSZ) format, for example, 1970-01-01T00:00:00.000Z.
update_time	String	Time when a private hook is updated. It uses a UTC (YYYY-MM-DDTHH:mm:ss.SSSZ) format, for example, 1970-01-01T00:00:00.000Z.

**Table 5** configuration
Parameter	Type	Description
target_stacks	String	Specifies the target stack where the private hook takes effect. The value can be NONE or ALL. NONE: Specifies that this private hook will not be applied to any stacks. ALL: Specifies that the private hook will be applied to all stacks under the account.
failure_mode	String	Specifies the behavior when the private hook validation fails. Valid values are FAIL or WARN. FAIL: Specifies that if this private hook validation fails, the stack will stop deploying, and the stack status will be updated to DEPLOYMENT_FAILED. WARN: Specifies that if this private hook validation fails, only a warning message will be displayed through the stack events, but it will not affect the deployment of the stack.

Status code: 400

**Table 6** Response body parameters
Parameter	Type	Description
error_code	String	Response code
error_msg	String	Response message

Status code: 401

**Table 7** Response body parameters
Parameter	Type	Description
error_code	String	Response code
error_msg	String	Response message

Status code: 403

**Table 8** Response body parameters
Parameter	Type	Description
error_code	String	Response code
error_msg	String	Response message

Status code: 429

**Table 9** Response body parameters
Parameter	Type	Description
error_code	String	Response code
error_msg	String	Response message

Status code: 500

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	Response code
error_msg	String	Response message

Example Requests

You can obtain all private hooks of the current account (domain) at the current region. The returned private hooks are sorted in descending order by creation time
```
GET https://{endpoint}/v1/private-hooks
```
You can obtain all private hooks of the current account (domain) at the current region. The returned private hooks are sorted in ascending order by creation time
```
GET https://{endpoint}/v1/private-hooks?sort_key=create_time&sort_dir=asc
```
You can obtain all private hooks of the current account (domain) at the current region. The returned private hooks are sorted in descending order by creation time
```
GET https://{endpoint}/v1/private-hooks?sort_key=create_time&sort_dir=desc
```

Example Responses

Status code: 200

List private hooks succeeded.

{
  "hooks" : [ {
    "hook_id" : "5009b614-184f-fdd0-2d29-a376b76184b6",
    "hook_name" : "test-hook-name-1",
    "hook_description" : "Test Hook1 Description",
    "default_version" : "1.2.3",
    "configuration" : {
      "target_stacks" : "NONE",
      "failure_mode" : "WARN"
    },
    "create_time" : "2024-06-01T01:00:00.000Z",
    "update_time" : "2024-06-01T02:00:00.000Z"
  }, {
    "hook_id" : "55a69e5a-6563-5358-86a0-e4be65312680",
    "hook_name" : "test-hook-name-2",
    "hook_description" : "Test Hook2 Description",
    "default_version" : "1.2.3",
    "configuration" : {
      "target_stacks" : "NONE",
      "failure_mode" : "WARN"
    },
    "create_time" : "2024-05-01T01:00:00.000Z",
    "update_time" : "2024-05-01T02:00:00.000Z"
  } ]
}

Status Codes

Status Code	Description
200	List private hooks succeeded.
400	Invalid request.
401	Authentication failed.
403	The user does not have the permission to call this API.
429	Too frequent requests.
500	Internal server error.