# Webhook Setup (Global and Repository-Only)

This bot accepts Gitea webhook events at:

- `POST /webhook/gitea`

It only processes these event types:

- `issue_comment`
- `pull_request_comment`

It verifies `X-Gitea-Signature` using `GITEA_WEBHOOK_SECRET` (HMAC-SHA256).

## Prerequisites

1. Bot is reachable from Gitea (example: `https://bot.example.com/webhook/gitea`).
2. `GITEA_WEBHOOK_SECRET` is set in your bot `.env`.
3. `ALLOWED_REPOS` includes repositories you want to allow (example: `team/repo-a,team/repo-b`).

## Option A: Global Webhook (single webhook, recommended)

Use this when you want one webhook configuration for many repositories.

1. In Gitea, open site administration webhook settings (instance-level/global webhooks).
2. Add a new webhook of type `Gitea` (JSON payload).
3. Set:
   - `Payload URL`: `https://bot.example.com/webhook/gitea`
   - `HTTP Method`: `POST`
   - `Secret`: same value as `GITEA_WEBHOOK_SECRET`
   - `Content Type`: `application/json`
4. Enable only these events:
   - `Issue comment`
   - `Pull request comment`
5. Save and use the webhook test/ping action.
6. Set `WEBHOOK_MODE=global` in bot env (informational, for deployment clarity).

Notes:

- The bot still enforces `ALLOWED_REPOS`; non-allowlisted repos are ignored.
- A global webhook is usually easiest to operate at scale.

## Option B: Repository-Only Webhook (per repository)

Use this when you want explicit repo-by-repo control.

1. Open the repository in Gitea.
2. Go to repository `Settings` -> `Webhooks`.
3. Add a new `Gitea` webhook.
4. Set:
   - `Payload URL`: `https://bot.example.com/webhook/gitea`
   - `HTTP Method`: `POST`
   - `Secret`: same value as `GITEA_WEBHOOK_SECRET`
   - `Content Type`: `application/json`
5. Enable only:
   - `Issue comment`
   - `Pull request comment`
6. Save and test.
7. Repeat for each repository.
8. Set `WEBHOOK_MODE=repo` in bot env.

Important:

- This bot has one configured secret (`GITEA_WEBHOOK_SECRET`) per bot instance.
- If multiple repo webhooks use different secrets, signature verification will fail for repos not matching the configured secret.

## Minimal `.env` snippet

```dotenv
GITEA_WEBHOOK_SECRET=replace-with-random-secret
ALLOWED_REPOS=team/repo-a,team/repo-b
WEBHOOK_MODE=global
```

For repo-only mode, use `WEBHOOK_MODE=repo`.

## Validation Checklist

1. `GET /healthz` returns `{"status":"ok"}`.
2. Webhook deliveries from Gitea return HTTP `200` (or bot returns accepted/ignored JSON, not `401`).
3. `401 invalid signature` means webhook secret mismatch.
4. `{"accepted": false, "reason": "repo not allowed"}` means update `ALLOWED_REPOS`.
5. A PR comment with `@codex review` on an allowlisted repo queues a job.