shithub Public

Watch 1 Fork 0 Star 0
markdown · 2959 bytes Raw Blame History

Webhooks

The webhook delivery format (payloads, signing) is shipped and stable. The webhook management API (CRUD over webhooks on a repo) is planned.

Delivery format

See Webhooks (user docs) for the full delivery contract — headers, body framing, signature verification, retries, idempotency.

The user-docs page is intentionally the canonical place; an API consumer building a subscriber endpoint reads the same material.

Management API (planned)

Method Path Scope
GET /api/v1/repos/{owner}/{repo}/hooks webhooks
POST /api/v1/repos/{owner}/{repo}/hooks webhooks
GET /api/v1/repos/{owner}/{repo}/hooks/{id} webhooks
PATCH /api/v1/repos/{owner}/{repo}/hooks/{id} webhooks
DELETE /api/v1/repos/{owner}/{repo}/hooks/{id} webhooks
POST /api/v1/repos/{owner}/{repo}/hooks/{id}/pings webhooks
GET /api/v1/repos/{owner}/{repo}/hooks/{id}/deliveries webhooks
POST /api/v1/repos/{owner}/{repo}/hooks/{id}/deliveries/{delivery}/redeliver webhooks

Until these land, manage webhooks via the web UI under Repository → Settings → Webhooks.

Event types (canonical list)

The events shippable today, by X-Shithub-Event header:

  • push
  • pull_request (actions: opened, closed, merged, reopened, edited, ready_for_review, converted_to_draft, synchronize)
  • pull_request_review (actions: submitted, dismissed)
  • pull_request_review_comment
  • issues (actions: opened, closed, reopened, edited, assigned, unassigned, labeled, unlabeled)
  • issue_comment
  • check_run (actions: created, completed, rerequested)
  • check_suite (actions: requested, completed, rerequested)
  • workflow_run (actions: queued, running, completed)
  • workflow_job (actions: queued, running, completed, cancelled)
  • star
  • fork
  • repository (actions: created, deleted, archived, unarchived, renamed, transferred, publicized, privatized)
  • ping (test event you trigger manually)

Each event's payload is documented per-type in the webhook detail page's "Recent deliveries" inspector — that's currently the authoritative reference until per-event documentation lands here.

Actions payload safety

workflow_run and workflow_job payloads are structural snapshots: ids, run index, workflow path/name, head SHA/ref, event kind, status, conclusion, timestamps, job key/name, runner id, needs, timeout, and cancellation state. They intentionally do not include workflow event payloads, env, permissions, logs, runner JWTs, or secret values.

View source
1 # Webhooks
2
3 The webhook **delivery format** (payloads, signing) is shipped
4 and stable. The webhook **management API** (CRUD over webhooks
5 on a repo) is planned.
6
7 ## Delivery format
8
9 See [Webhooks (user docs)](../user/webhooks.md) for the full
10 delivery contract — headers, body framing, signature verification,
11 retries, idempotency.
12
13 The user-docs page is intentionally the canonical place; an API
14 consumer building a subscriber endpoint reads the same material.
15
16 ## Management API (planned)
17
18 | Method | Path | Scope |
19 |--------|-----------------------------------------------------------|--------------|
20 | GET | `/api/v1/repos/{owner}/{repo}/hooks` | `webhooks` |
21 | POST | `/api/v1/repos/{owner}/{repo}/hooks` | `webhooks` |
22 | GET | `/api/v1/repos/{owner}/{repo}/hooks/{id}` | `webhooks` |
23 | PATCH | `/api/v1/repos/{owner}/{repo}/hooks/{id}` | `webhooks` |
24 | DELETE | `/api/v1/repos/{owner}/{repo}/hooks/{id}` | `webhooks` |
25 | POST | `/api/v1/repos/{owner}/{repo}/hooks/{id}/pings` | `webhooks` |
26 | GET | `/api/v1/repos/{owner}/{repo}/hooks/{id}/deliveries` | `webhooks` |
27 | POST | `/api/v1/repos/{owner}/{repo}/hooks/{id}/deliveries/{delivery}/redeliver` | `webhooks` |
28
29 Until these land, manage webhooks via the web UI under
30 Repository → Settings → Webhooks.
31
32 ## Event types (canonical list)
33
34 The events shippable today, by `X-Shithub-Event` header:
35
36 - `push`
37 - `pull_request` (actions: `opened`, `closed`, `merged`,
38 `reopened`, `edited`, `ready_for_review`, `converted_to_draft`,
39 `synchronize`)
40 - `pull_request_review` (actions: `submitted`, `dismissed`)
41 - `pull_request_review_comment`
42 - `issues` (actions: `opened`, `closed`, `reopened`, `edited`,
43 `assigned`, `unassigned`, `labeled`, `unlabeled`)
44 - `issue_comment`
45 - `check_run` (actions: `created`, `completed`, `rerequested`)
46 - `check_suite` (actions: `requested`, `completed`,
47 `rerequested`)
48 - `workflow_run` (actions: `queued`, `running`, `completed`)
49 - `workflow_job` (actions: `queued`, `running`, `completed`,
50 `cancelled`)
51 - `star`
52 - `fork`
53 - `repository` (actions: `created`, `deleted`, `archived`,
54 `unarchived`, `renamed`, `transferred`, `publicized`,
55 `privatized`)
56 - `ping` (test event you trigger manually)
57
58 Each event's payload is documented per-type in the webhook detail
59 page's "Recent deliveries" inspector — that's currently the
60 authoritative reference until per-event documentation lands here.
61
62 ### Actions payload safety
63
64 `workflow_run` and `workflow_job` payloads are structural snapshots:
65 ids, run index, workflow path/name, head SHA/ref, event kind, status,
66 conclusion, timestamps, job key/name, runner id, needs, timeout, and
67 cancellation state. They intentionally do **not** include workflow
68 event payloads, env, permissions, logs, runner JWTs, or secret values.