---
title: "Create a system hook"
method: POST
path: "/api/v4/hooks"
tags: ["hooks"]
---

# Create a system hook

`POST /api/v4/hooks`

## Request

- Base URL: `https://gitlab.com`
- URL: `https://gitlab.com/api/v4/hooks`
- Auth: none declared

Creates a system hook. This endpoint has a rate limit of five requests per minute for each authenticated user. On GitLab Self-Managed and GitLab Dedicated, an administrator can change this limit in the application settings.

## Request body

- PostApiV4Hooks: Create a system hook
  - `url` string, required: The URL to send the request to
  - `name` string: Name of the hook
  - `description` string: Description of the hook
  - `token` string: Secret token to validate received payloads; this isn't returned in the response
  - `signing_token` string: HMAC signing token used to compute the webhook-signature header. Must be in whsec_<base64> format encoding a 32-byte key. Not returned in the response
  - `push_events` boolean: When true, the hook fires on push events
  - `tag_push_events` boolean: When true, the hook fires on new tags being pushed
  - `merge_requests_events` boolean: Trigger hook on merge requests events
  - `repository_update_events` boolean: Trigger hook on repository update events
  - `enable_ssl_verification` boolean: Do SSL verification when triggering the hook
  - `push_events_branch_filter` string: Trigger hook on specified branch only
  - `branch_filter_strategy` 'wildcard' | 'regex' | 'all_branches': Filter push events by branch. Possible values are `wildcard` (default), `regex`, and `all_branches`
  - `custom_webhook_template` string: Custom template for the request payload
  - `url_variables` object[]: URL variables for interpolation
    - `key` string, required: Name of the variable
    - `value` string, required: Value of the variable
  - `custom_headers` object[]: Custom headers
    - `key` string, required: Name of the header
    - `value` string, required: Value of the header

## Response `201`

Create a system hook

- APIEntitiesHook: API_Entities_Hook model
  - `id` integer, required
  - `url` string, required
  - `name` string, required
  - `description` string, required
  - `created_at` string, date-time, required
  - `push_events` boolean, required
  - `tag_push_events` boolean, required
  - `merge_requests_events` boolean, required
  - `repository_update_events` boolean, required
  - `enable_ssl_verification` boolean, required
  - `organization_id` integer
  - `alert_status` string, required
  - `disabled_until` string, date-time, required
  - `url_variables` object[]
  - `push_events_branch_filter` string, required
  - `branch_filter_strategy` string, required
  - `custom_webhook_template` string, required
  - `custom_headers` object[]
  - `token_present` boolean, required: Whether a secret token is configured
  - `signing_token_present` boolean, required: Whether an HMAC signing token is configured

## Other responses

- `400`: Validation error
- `404`: Not found
- `422`: Unprocessable entity
- `429`: Too many requests

## Changes

- **2026-10-23** `b63fd3ced595`: 1 info
  - added the non-success response with the status `429`

[Operation history](https://skmtc.dev/gitlab/apis/gitlab-api/changes/api/v4/hooks/post.md)

---

[API](https://skmtc.dev/gitlab/apis/gitlab-api.md) - [All operations](https://skmtc.dev/gitlab/apis/gitlab-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gitlab/apis/gitlab-api/revisions/b234947ef3f2?raw)