Create repository webhooks¶

POST /api/v5/repos/{owner}/{repo}/hooks

This endpoint creates webhooks for the specified repository. You can set the remote HTTP URL that receives events, the request password, and the encryption type, and configure whether events such as push code, push tag, issue creation or closure, comments, and merge requests trigger deliveries.

Supported access tokens¶

AtomGit user access token (AtomGit user access tokens)

Anonymous access¶

This endpoint does not allow anonymous access.

Request parameters¶

Parameter	Location	Type	Required	Description
`owner`	path	string	Yes	Address path of the namespace that owns the repository (the address path of an enterprise, organization, or individual)
`repo`	path	string	Yes	Repository path (path)
`access_token`	query	string	Yes	User authorization code

Request Body:

The request body is submitted as JSON (Content-Type: application/json) or a form (application/x-www-form-urlencoded). The JSON schema is as follows:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "description": "Remote HTTP URL",
      "type": "string"
    },
    "encryption_type": {
      "description": "Encryption type: 0 password (X-GitCode-Token), 1 signing secret (X-GitCode-Secret); defaults to 0 when omitted",
      "type": "integer",
      "enum": [0, 1],
      "default": 0
    },
    "password": {
      "description": "This password is included when requesting the URL to prevent malicious requests to the URL",
      "type": "string"
    },
    "push_events": {
      "description": "Push code to the repository",
      "type": "boolean",
      "default": false
    },
    "tag_push_events": {
      "description": "Push a tag to the repository",
      "type": "boolean",
      "default": false
    },
    "issues_events": {
      "description": "Create/close an issue",
      "type": "boolean",
      "default": false
    },
    "note_events": {
      "description": "Comment on an issue, code, and so on",
      "type": "boolean",
      "default": false
    },
    "merge_requests_events": {
      "description": "Merge request and after merge",
      "type": "boolean",
      "default": false
    }
  },
  "required": ["url"]
}

Note: In addition to authenticating with the access_token query parameter, the request body can also carry an access_token field (the request body object inherits from AuthTokenBody). The server uses the token in the request body first.

Response parameters¶

Field	Type	Always returned	Nullable	Description
`id`	integer	Yes	No	Webhook ID
`url`	string	Yes	No	Remote HTTP URL
`password`	string	Yes	Yes	Password included when requesting the URL
`result`	string	Yes	Yes	Result of the most recent push, may be `null`
`project_id`	integer	Yes	No	Project (repository) ID
`result_code`	integer	Yes	Yes	Status code of the most recent push result, may be `null`
`push_events`	boolean	Yes	No	Whether to deliver push code events
`tag_push_events`	boolean	Yes	No	Whether to deliver tag push events
`issues_events`	boolean	Yes	No	Whether to deliver issue creation/closure events
`note_events`	boolean	Yes	No	Whether to deliver comment (issue/code, etc.) events
`merge_requests_events`	boolean	Yes	No	Whether to deliver merge request (including after merge) events
`created_at`	string	Yes	No	Creation time
`active`	boolean	Yes	Yes	Whether enabled, may be `null`

Error response¶

Error responses return their error fields in the ApiErrorResp structure (snake_case field names: error_code / error_code_name / error_message).

400 Invalid parameters

{
  "error_code": 400,
  "error_code_name": "BAD_REQUEST",
  "error_message": "Invalid encryption type"
}

401 Unauthenticated

{
  "error_code": 401,
  "error_code_name": "BadCredentials",
  "error_message": "401, token not found"
}

403 Forbidden

{
  "error_code": 403,
  "error_code_name": "FORBIDDEN",
  "error_message": "no scopes:all_hook"
}

HTTP status codes¶

Status code	Description
`200`	Success (OK)
`400`	Invalid parameters (Bad Request)
`401`	Requires authentication
`403`	Forbidden
`404`	Resource not found (Not found)
`429`	Too many requests, rate limit triggered (Rate limited)
`500`	Internal server error

Request example¶

Parameter description¶

Replace <owner> with the address path of the namespace that owns the repository (the address path of an enterprise, organization, or individual); replace <repo> with the repository path (path); replace <token> with your AtomGit user access token.

cURL¶

curl -X POST 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/hooks?access_token=<token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/webhook",
  "encryption_type": 0,
  "password": "123456",
  "push_events": true,
  "tag_push_events": false,
  "issues_events": true,
  "note_events": false,
  "merge_requests_events": true
}'

JavaScript¶

// Native fetch (Node.js 18+ / browser)
const owner = "<owner>";
const repo = "<repo>";
const token = "<token>";
const url = `https://api.atomgit.com/api/v5/repos/${owner}/${repo}/hooks?access_token=${token}`;

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    url: "https://example.com/webhook",
    encryption_type: 0,
    password: "123456",
    push_events: true,
    tag_push_events: false,
    issues_events: true,
    note_events: false,
    merge_requests_events: true
  })
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python¶

import requests

owner = "<owner>"
repo = "<repo>"
token = "<token>"

resp = requests.post(
    f"https://api.atomgit.com/api/v5/repos/{owner}/{repo}/hooks",
    params={"access_token": token},
    json={
        "url": "https://example.com/webhook",
        "encryption_type": 0,
        "password": "123456",
        "push_events": True,
        "tag_push_events": False,
        "issues_events": True,
        "note_events": False,
        "merge_requests_events": True,
    },
    headers={"Accept": "application/json"},
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

{
  "id": 9529,
  "url": "https://example.com/webhook",
  "password": "123456",
  "result": null,
  "project_id": 282463,
  "result_code": 0,
  "push_events": true,
  "tag_push_events": false,
  "issues_events": true,
  "note_events": false,
  "merge_requests_events": true,
  "created_at": "2024-09-26T16:13:27+08:00",
  "active": true
}

Error codes¶

Error code	Description
`400`	Invalid parameters or the request cannot be parsed
`401`	Unauthenticated or invalid credentials (missing or invalid access token)
`403`	No permission (missing the required token scope, such as `all_hook`)
`404`	Request path does not exist
`429`	Too many requests, rate limit triggered
`500`	Internal system error

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc