GIgitlab
hooks

Create a system hook

Changed on

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.

post/api/v4/hooks

Request

  • Base URL
    https://gitlab.com
  • Auth
    none declared

Request body

urlstring required

The URL to send the request to

namestring

Name of the hook

descriptionstring

Description of the hook

tokenstring

Secret token to validate received payloads; this isn't returned in the response

signing_tokenstring

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_eventsboolean

When true, the hook fires on push events

tag_push_eventsboolean

When true, the hook fires on new tags being pushed

merge_requests_eventsboolean

Trigger hook on merge requests events

repository_update_eventsboolean

Trigger hook on repository update events

enable_ssl_verificationboolean

Do SSL verification when triggering the hook

push_events_branch_filterstring

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_templatestring

Custom template for the request payload

Example request

{
  "url": "http://example.com/hook",
  "url_variables": [
    {
      "key": "token",
      "value": "123"
    }
  ],
  "custom_headers": [
    {
      "key": "X-Custom-Header",
      "value": "value"
    }
  ]
}

Response

Create a system hook

idinteger required
urlstring required
namestring required
descriptionstring required
created_atstring date-time required
push_eventsboolean required
tag_push_eventsboolean required
merge_requests_eventsboolean required
repository_update_eventsboolean required
enable_ssl_verificationboolean required
organization_idinteger
alert_statusstring required
disabled_untilstring date-time required
url_variablesobject[]
push_events_branch_filterstring required
branch_filter_strategystring required
custom_webhook_templatestring required
custom_headersobject[]
token_presentboolean required

Whether a secret token is configured

signing_token_presentboolean required

Whether an HMAC signing token is configured

Example response

{
  "id": 1,
  "url": "https://webhook.site",
  "name": "Hook name",
  "description": "Hook description",
  "created_at": "2012-05-28T04:42:42-07:00",
  "organization_id": 1,
  "alert_status": "executable",
  "disabled_until": "2012-05-28T04:42:42-07:00",
  "url_variables": [
    {
      "token": "secr3t"
    }
  ],
  "push_events_branch_filter": "my-branch-*",
  "branch_filter_strategy": "wildcard",
  "custom_webhook_template": "{\"event\":\"{{object_kind}}\"}",
  "custom_headers": [
    {
      "X-Custom-Header": "value"
    }
  ]
}

Changes