# Webhooks API

## Repository Webhooks

### List Hooks

```
GET /api/v1/repos/{owner}/{repo}/hooks
```

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/hooks" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Create Hook

```
POST /api/v1/repos/{owner}/{repo}/hooks
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/hooks" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "forgejo",
    "config": {
      "url": "https://webhook.example.com/hook",
      "content_type": "json",
      "secret": "{webhook_secret}"
    },
    "events": ["push", "pull_request", "issues"],
    "active": true
  }'
```

### Get Hook

```
GET /api/v1/repos/{owner}/{repo}/hooks/{id}
```

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/hooks/{hook_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Edit Hook

```
PATCH /api/v1/repos/{owner}/{repo}/hooks/{id}
```

```bash
curl -s -X PATCH "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/hooks/{hook_id}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["push", "pull_request", "issues", "release"],
    "active": true
  }'
```

### Delete Hook

```
DELETE /api/v1/repos/{owner}/{repo}/hooks/{id}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/hooks/{hook_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Test Hook

```
POST /api/v1/repos/{owner}/{repo}/hooks/{id}/tests
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/hooks/{hook_id}/tests" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Organization Webhooks

### List Org Hooks

```
GET /api/v1/orgs/{org}/hooks
```

```bash
curl -s "${FORGEJO_URL}/api/v1/orgs/{org}/hooks" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Create Org Hook

```
POST /api/v1/orgs/{org}/hooks
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/orgs/{org}/hooks" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "slack",
    "config": {
      "url": "https://hooks.slack.com/services/XXX/YYY/ZZZ",
      "content_type": "json"
    },
    "events": ["push", "pull_request", "release"],
    "active": true
  }'
```

### Get Org Hook

```
GET /api/v1/orgs/{org}/hooks/{id}
```

```bash
curl -s "${FORGEJO_URL}/api/v1/orgs/{org}/hooks/{hook_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Edit Org Hook

```
PATCH /api/v1/orgs/{org}/hooks/{id}
```

```bash
curl -s -X PATCH "${FORGEJO_URL}/api/v1/orgs/{org}/hooks/{hook_id}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'
```

### Delete Org Hook

```
DELETE /api/v1/orgs/{org}/hooks/{id}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/orgs/{org}/hooks/{hook_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## User Webhooks

### List User Hooks

```
GET /api/v1/user/hooks
```

```bash
curl -s "${FORGEJO_URL}/api/v1/user/hooks" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Create User Hook

```
POST /api/v1/user/hooks
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/user/hooks" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "forgejo",
    "config": {
      "url": "https://webhook.example.com/user-hook",
      "content_type": "json",
      "secret": "{webhook_secret}"
    },
    "events": ["repository", "release"],
    "active": true
  }'
```

### Get User Hook

```
GET /api/v1/user/hooks/{id}
```

```bash
curl -s "${FORGEJO_URL}/api/v1/user/hooks/{hook_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Edit User Hook

```
PATCH /api/v1/user/hooks/{id}
```

```bash
curl -s -X PATCH "${FORGEJO_URL}/api/v1/user/hooks/{hook_id}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'
```

### Delete User Hook

```
DELETE /api/v1/user/hooks/{id}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/user/hooks/{hook_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## System Webhooks (Admin)

Requires admin privileges.

### List System Hooks

```
GET /api/v1/admin/hooks
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/hooks" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Create System Hook

```
POST /api/v1/admin/hooks
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/admin/hooks" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "forgejo",
    "config": {
      "url": "https://audit.example.com/system-hook",
      "content_type": "json",
      "secret": "{webhook_secret}",
      "is_system_webhook": "true"
    },
    "events": ["repository", "push", "create", "delete"],
    "active": true
  }'
```

### Get System Hook

```
GET /api/v1/admin/hooks/{id}
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/hooks/{hook_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Edit System Hook

```
PATCH /api/v1/admin/hooks/{id}
```

```bash
curl -s -X PATCH "${FORGEJO_URL}/api/v1/admin/hooks/{hook_id}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"active": true, "events": ["repository", "push"]}'
```

### Delete System Hook

```
DELETE /api/v1/admin/hooks/{id}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/admin/hooks/{hook_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Git Hooks (Repository)

Low-level git hooks for a repository.

### List Git Hooks

```
GET /api/v1/repos/{owner}/{repo}/hooks/git
```

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/hooks/git" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Get Git Hook

```
GET /api/v1/repos/{owner}/{repo}/hooks/git/{id}
```

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/hooks/git/pre-receive" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Edit Git Hook

```
PATCH /api/v1/repos/{owner}/{repo}/hooks/git/{id}
```

```bash
curl -s -X PATCH "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/hooks/git/pre-receive" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"content": "#!/bin/sh\necho \"Pre-receive hook\"\nexit 0"}'
```

### Delete Git Hook

```
DELETE /api/v1/repos/{owner}/{repo}/hooks/git/{id}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/hooks/git/pre-receive" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## CreateHookOption Reference

### type (required)

Supported hook types:

| Type | Description |
|------|-------------|
| `forgejo` | Forgejo/Gitea webhook |
| `dingtalk` | DingTalk |
| `discord` | Discord |
| `gitea` | Gitea (alias for forgejo) |
| `gogs` | Gogs |
| `msteams` | Microsoft Teams |
| `slack` | Slack |
| `telegram` | Telegram |
| `feishu` | Feishu/Lark |
| `wechatwork` | WeChat Work |
| `packagist` | Packagist |

### config (required)

| Field | Type | Description |
|-------|------|-------------|
| `url` | string | Webhook target URL |
| `content_type` | string | `json` or `form` |
| `secret` | string | Webhook secret for signature verification |
| `is_system_webhook` | string | `"true"` for system-level hooks |

### events (array)

Available webhook event types:

| Event | Description |
|-------|-------------|
| `push` | Push to repository |
| `create` | Branch or tag created |
| `delete` | Branch or tag deleted |
| `fork` | Repository forked |
| `issues` | Issue opened, closed, reopened |
| `issue_assign` | Issue assigned/unassigned |
| `issue_label` | Issue label added/removed |
| `issue_milestone` | Issue milestone changed |
| `issue_comment` | Comment on issue |
| `pull_request` | PR opened, closed, reopened, merged |
| `pull_request_assign` | PR assigned/unassigned |
| `pull_request_label` | PR label added/removed |
| `pull_request_milestone` | PR milestone changed |
| `pull_request_comment` | Comment on PR |
| `pull_request_review` | PR review submitted |
| `repository` | Repository created, deleted, etc. |
| `release` | Release published |
| `package` | Package published |
| `wiki` | Wiki page created, edited, deleted |

### Other fields

| Field | Type | Description |
|-------|------|-------------|
| `active` | boolean | Whether the hook is active |
| `authorization_header` | string | Custom Authorization header |
| `branch_filter` | string | Glob pattern to filter branches (e.g., `main`, `release/*`) |

---

## Complete Examples

### Discord webhook for PRs

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/hooks" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "discord",
    "config": {
      "url": "https://discord.com/api/webhooks/123456/abcdef"
    },
    "events": ["pull_request", "pull_request_review", "pull_request_comment"],
    "active": true
  }'
```

### Slack webhook for releases only on main

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/hooks" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "slack",
    "config": {
      "url": "https://hooks.slack.com/services/T00/B00/XXXX"
    },
    "events": ["release"],
    "active": true,
    "branch_filter": "{branch_pattern}"
  }'
```

### Webhook with custom auth header

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/hooks" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "forgejo",
    "config": {
      "url": "https://ci.example.com/webhook",
      "content_type": "json",
      "secret": "{webhook_secret}"
    },
    "events": ["push", "pull_request"],
    "active": true,
    "authorization_header": "Bearer {token}"
  }'
```
