system_hooks.md 2.81 KB
Newer Older
1
# System hooks API
2

3
All methods require administrator authorization.
4

5
The URL endpoint of the system hooks can also be configured using the UI in
6 7 8
the admin area under **Hooks** (`/admin/hooks`).

Read more about [system hooks](../system_hooks/system_hooks.md).
9 10 11

## List system hooks

12
Get a list of all system hooks.
13

14 15
---

16 17 18 19
```
GET /hooks
```

20 21
Example request:

22
```bash
23
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/hooks
24
```
25

26
Example response:
27 28 29

```json
[
30 31 32 33 34 35
  {
    "id":1,
    "url":"https://gitlab.example.com/hook",
    "created_at":"2016-10-31T12:32:15.192Z",
    "push_events":true,
    "tag_push_events":false,
36
    "merge_requests_events": true,
37
    "repository_update_events": true,
38 39
    "enable_ssl_verification":true
  }
40 41 42
]
```

43
## Add new system hook
44

45 46 47 48
Add a new system hook.

---

49 50 51 52
```
POST /hooks
```

53 54 55
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `url` | string | yes | The hook URL |
56 57 58
| `token` | string | no | Secret token to validate received payloads; this will not be returned in the response |
| `push_events` | boolean |  no | When true, the hook will fire on push events |
| `tag_push_events` | boolean | no | When true, the hook will fire on new tags being pushed |
59
| `merge_requests_events` | boolean | no | Trigger hook on merge requests events |
60
| `repository_update_events` | boolean | no | Trigger hook on repository update events |
61
| `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook |
62

63 64
Example request:

65
```bash
66
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/hooks?url=https://gitlab.example.com/hook"
67
```
68

69 70 71 72
Example response:

```json
[
73 74 75 76 77 78
  {
    "id":1,
    "url":"https://gitlab.example.com/hook",
    "created_at":"2016-10-31T12:32:15.192Z",
    "push_events":true,
    "tag_push_events":false,
79
    "merge_requests_events": true,
80
    "repository_update_events": true,
81 82
    "enable_ssl_verification":true
  }
83 84
]
```
85 86 87 88 89 90 91

## Test system hook

```
GET /hooks/:id
```

92 93 94
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the hook |
95

96 97
Example request:

98
```bash
99
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/hooks/2
100 101 102
```

Example response:
103 104 105

```json
{
106 107 108 109 110 111
   "project_id" : 1,
   "owner_email" : "example@gitlabhq.com",
   "owner_name" : "Someone",
   "name" : "Ruby",
   "path" : "ruby",
   "event_name" : "project_create"
112 113 114 115 116
}
```

## Delete system hook

117
Deletes a system hook.
118 119

---
120 121 122 123 124

```
DELETE /hooks/:id
```

125 126 127 128
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the hook |

129 130
Example request:

131
```bash
132
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/hooks/2
133
```