# GitLab Hooks API

**Canonical:** https://apis.io/apis/gitlab/gitlab-hooks-api/  
**Provider:** GitLab — https://apis.io/providers/gitlab/  
**Base URL:** https://gitlab.com/api/v4  
**Documentation:** https://docs.gitlab.com/api/rest/

GitLab Hooks API is one of 189 APIs that [GitLab](https://apis.io/providers/gitlab/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification. This API exposes 16 JSON Schema definitions. Tagged areas include Hooks. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, authentication docs, an API reference, rate-limit docs, an AsyncAPI specification, and 16 JSON Schemas.

Use this API to manage the hooks that GitLab uses to notify external services about events: - [Project webhooks](https://docs.gitlab.com/user/project/integrations/webhooks/) are limited to a single project. - [Group webhooks](https://docs.gitlab.com/user/project/integrations/webhooks/#group-webhooks) apply to all projects and subgroups in a group. - [System hooks](https://docs.gitlab.com/administration/system_hooks/) apply to the entire instance. You can also test a hook, inspect its event log, resend an event, and manage its custom headers and URL variables. Managing project webhooks requires administrator access or the Maintainer or Owner role for the project. Managing group webhooks requires administrator access or the Owner role for the group. Managing system hooks requires administrator access.

## Operations (34)

| Method | Path | Summary |
|---|---|---|
| GET | `/api/v4/groups/{id}/hooks` | List all group hooks |
| POST | `/api/v4/groups/{id}/hooks` | Create a group hook |
| GET | `/api/v4/groups/{id}/hooks/{hook_id}` | Retrieve a group hook |
| PUT | `/api/v4/groups/{id}/hooks/{hook_id}` | Update a group hook |
| DELETE | `/api/v4/groups/{id}/hooks/{hook_id}` | Delete a group hook |
| GET | `/api/v4/groups/{id}/hooks/{hook_id}/events` | List all events |
| PUT | `/api/v4/groups/{id}/hooks/{hook_id}/url_variables/{key}` | Update a URL variable |
| DELETE | `/api/v4/groups/{id}/hooks/{hook_id}/url_variables/{key}` | Delete a URL variable |
| PUT | `/api/v4/groups/{id}/hooks/{hook_id}/custom_headers/{key}` | Update a custom header |
| DELETE | `/api/v4/groups/{id}/hooks/{hook_id}/custom_headers/{key}` | Delete a custom header |
| POST | `/api/v4/groups/{id}/hooks/{hook_id}/test/{trigger}` | Trigger a test webhook |
| POST | `/api/v4/groups/{id}/hooks/{hook_id}/events/{hook_log_id}/resend` | Resend a webhook event |
| PUT | `/api/v4/hooks/{hook_id}/url_variables/{key}` | Update a URL variable |
| DELETE | `/api/v4/hooks/{hook_id}/url_variables/{key}` | Delete a URL variable |
| PUT | `/api/v4/hooks/{hook_id}/custom_headers/{key}` | Update a custom header |
| DELETE | `/api/v4/hooks/{hook_id}/custom_headers/{key}` | Delete a custom header |
| GET | `/api/v4/hooks` | List all system hooks |
| POST | `/api/v4/hooks` | Create a system hook |
| GET | `/api/v4/hooks/{hook_id}` | Retrieve a system hook |
| PUT | `/api/v4/hooks/{hook_id}` | Update a system hook |
| POST | `/api/v4/hooks/{hook_id}` | Create a test run |
| DELETE | `/api/v4/hooks/{hook_id}` | Delete a system hook |
| PUT | `/api/v4/projects/{id}/hooks/{hook_id}/url_variables/{key}` | Update a URL variable |
| DELETE | `/api/v4/projects/{id}/hooks/{hook_id}/url_variables/{key}` | Delete a URL variable |
| PUT | `/api/v4/projects/{id}/hooks/{hook_id}/custom_headers/{key}` | Update a custom header |
| DELETE | `/api/v4/projects/{id}/hooks/{hook_id}/custom_headers/{key}` | Delete a custom header |
| GET | `/api/v4/projects/{id}/hooks` | List all webhooks for a project |
| POST | `/api/v4/projects/{id}/hooks` | Add a webhook to a project |
| GET | `/api/v4/projects/{id}/hooks/{hook_id}` | Retrieve a project webhook |
| PUT | `/api/v4/projects/{id}/hooks/{hook_id}` | Update a project webhook |
| DELETE | `/api/v4/projects/{id}/hooks/{hook_id}` | Delete a project webhook |
| GET | `/api/v4/projects/{id}/hooks/{hook_id}/events` | List all events |
| POST | `/api/v4/projects/{id}/hooks/{hook_id}/test/{trigger}` | Trigger a test webhook |
| POST | `/api/v4/projects/{id}/hooks/{hook_id}/events/{hook_log_id}/resend` | Resend a webhook event |

## Machine-readable artifacts (65)

- **OpenAPI** — https://artifacts.apis.io/gitlab/openapi/gitlab-hooks-api-openapi.yml
- **Documentation** — https://docs.gitlab.com/api/openapi/
- **Documentation** — https://docs.gitlab.com/api/issues/
- **Authentication** — https://docs.gitlab.com/api/rest/authentication/
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-put-api-v4-application-settings-request-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-apientities-geo-node-status-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-apientities-geo-site-status-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-apientities-application-setting-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-post-api-v4-geo-status-request-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-put-api-v4-projects-id-request-schema.json
- **Documentation** — https://docs.gitlab.com/api/merge_requests/
- **Documentation** — https://docs.gitlab.com/api/pipelines/
- **Documentation** — https://docs.gitlab.com/api/jobs/
- **Documentation** — https://docs.gitlab.com/api/runners/
- **Documentation** — https://docs.gitlab.com/api/users/
- **Documentation** — https://docs.gitlab.com/api/repositories/
- **Documentation** — https://docs.gitlab.com/api/commits/
- **Documentation** — https://docs.gitlab.com/api/branches/
- **Documentation** — https://docs.gitlab.com/api/tags/
- **Documentation** — https://docs.gitlab.com/api/releases/
- **Documentation** — https://docs.gitlab.com/api/environments/
- **Documentation** — https://docs.gitlab.com/api/deployments/
- **Documentation** — https://docs.gitlab.com/api/pipeline_schedules/
- **Documentation** — https://docs.gitlab.com/api/labels/
- **Documentation** — https://docs.gitlab.com/api/milestones/
- **Documentation** — https://docs.gitlab.com/api/notes/
- **Documentation** — https://docs.gitlab.com/api/snippets/
- **Documentation** — https://docs.gitlab.com/api/packages/
- **Documentation** — https://docs.gitlab.com/api/container_registry/
- **Documentation** — https://docs.gitlab.com/api/vulnerabilities/
- **Documentation** — https://docs.gitlab.com/api/deploy_keys/
- **Documentation** — https://docs.gitlab.com/api/protected_branches/
- **Documentation** — https://docs.gitlab.com/api/wikis/
- **Documentation** — https://docs.gitlab.com/api/events/
- **Documentation** — https://docs.gitlab.com/api/search/
- **Documentation** — https://docs.gitlab.com/api/namespaces/
- **Documentation** — https://docs.gitlab.com/api/groups/
- **Documentation** — https://docs.gitlab.com/api/projects/
- **Documentation** — https://docs.gitlab.com/api/applications/
- **Documentation** — https://docs.gitlab.com/api/avatar/
- …and 25 more, listed in full on the page.

## Other GitLab APIs (12)

- [GitLab Orbit gRPC API](https://apis.io/apis/gitlab/gitlab-orbit-api/)
- [GitLab GraphQL API](https://apis.io/apis/gitlab/gitlab-graphql-api/)
- [GitLab Applications API](https://apis.io/apis/gitlab/gitlab-applications-api/)
- [GitLab Authorization API](https://apis.io/apis/gitlab/gitlab-authorization-api/)
- [GitLab Broadcast Messages API](https://apis.io/apis/gitlab/gitlab-broadcast-messages-api/)
- [GitLab Groups API](https://apis.io/apis/gitlab/gitlab-groups-api/)
- [GitLab Metadata API](https://apis.io/apis/gitlab/gitlab-metadata-api/)
- [GitLab Project Webhooks API](https://apis.io/apis/gitlab/gitlab-project-webhooks-api/)
- [GitLab Projects API](https://apis.io/apis/gitlab/gitlab-projects-api/)
- [GitLab Tokens API](https://apis.io/apis/gitlab/gitlab-tokens-api/)
- [GitLab User Info API](https://apis.io/apis/gitlab/gitlab-user-info-api/)
- [GitLab Webhook Configuration API](https://apis.io/apis/gitlab/gitlab-webhook-configuration-api/)

## Tags

Hooks

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/gitlab/gitlab-hooks-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/gitlab/.