#+title: gitbay API and webhooks

* The JSON API

One endpoint fronts the entire command registry — everything the SSH
control plane can do, current and future, with identical semantics.
Disabled by default; the instance must set:

#+begin_src toml
[api]
enabled = true
#+end_src

** Tokens

Tokens are minted over SSH and only over SSH — an API token can never
create further credentials.

#+begin_src sh
gitbay auth token create --name ci [--scope full|read] [--ttl 30d]
gitbay auth token list
gitbay auth token revoke ci
#+end_src

The token (prefix =gb_=, shown exactly once) is presented as
=Authorization: Bearer gb_...=. Only a hash is stored server-side.
Scope =read= permits list/show/log/diff-style commands and refuses
anything that modifies state. =--ttl= takes Go durations or a day
suffix (=30d=); expired, revoked, and unknown tokens all answer the
same 401.

** POST /api/v1/cmd

Request body:
#+begin_src json
{"argv": ["issue", "create", "you/project", "--title", "from CI"],
 "stdin": "optional body for --file - style input"}
#+end_src

=argv= is real argv — no shell, no quoting rules. The response is the
command's own JSON envelope with =exit_code= added, plus =stderr= when
the command wrote diagnostics:

#+begin_src json
{"protocol_version": 1, "exit_code": 0, "data": {"number": 7}}
#+end_src

HTTP status maps the exit code: 0→200, 2→400, 3→404, 4→403, else 500.
Commands that emit raw text rather than an envelope (=help=, =mr diff=)
come wrapped as ={"output": "..."}=. Git transport commands and the
token commands are refused by name.

#+begin_src sh
curl -s -H "Authorization: Bearer $TOKEN" \
     -d '{"argv":["whoami"]}' https://gitbay.org/api/v1/cmd

printf '{"argv":["issue","create","you/project","--title","t","--file","-"],"stdin":"body\n"}' |
curl -s -H "Authorization: Bearer $TOKEN" -d @- https://gitbay.org/api/v1/cmd
#+end_src

* Webhooks

Per-repository outbound POSTs for repository events. Managed by repo
admins:

#+begin_src sh
gitbay webhook add <url> --secret s3cret [--events push,issue.created]  # default *
gitbay webhook list
gitbay webhook deliveries [--limit 50]     # status, attempts, last error
gitbay webhook redeliver <delivery-id>     # requeue, including dead letters
gitbay webhook remove <id>
#+end_src

** Events

=push= (data: ref, old, new, forced, deleted), =issue.created=,
=issue.commented=, =issue.closed=, =issue.open=, =mr.created=,
=mr.merged= (data: number, sha), =repo.imported= (data: from).

** Delivery

Each event POSTs one JSON body:

#+begin_src json
{"event": "push",
 "repo": "you/project",
 "actor": "alice",
 "created_at": "2026-08-24T01:00:00.000Z",
 "data": {"ref": "refs/heads/main", "old": "...", "new": "...",
          "forced": false, "deleted": false}}
#+end_src

Headers: =X-Gitbay-Event=, =X-Gitbay-Delivery= (id), and — when the hook
has a secret — =X-Gitbay-Signature-256: sha256=<hex hmac>= over the raw
body. Verify before trusting:

#+begin_src python
import hmac, hashlib
expected = "sha256=" + hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, request.headers["X-Gitbay-Signature-256"])
#+end_src

A 2xx within 10 seconds is success. Anything else retries with
exponential backoff (30s base, doubling) and dead-letters after five
attempts; =webhook deliveries= shows the trail and =redeliver= revives a
dead letter. Redirects are never followed, and targets resolving to
loopback/private/link-local addresses are refused both at registration
and again at connect time, unless the instance sets
=[webhooks] allow_local=.