| 1 | --- |
| 2 | title: Webhooks |
| 3 | description: Have g1t send a repository's or a workspace's events to your own address as they happen, signed and retried. |
| 4 | --- |
| 5 | |
| 6 | A webhook sends events to an HTTPS address you choose, as they happen: a |
| 7 | push, an issue opened, a pull request merged, checks finished, the merge |
| 8 | queue moving. Use them to build on g1t: post to chat, start a deploy, keep |
| 9 | another system in step. |
| 10 | |
| 11 | A webhook belongs to one of two things: |
| 12 | |
| 13 | | | Sent the events of | Managed by | Where | |
| 14 | | --- | --- | --- | --- | |
| 15 | | A repository's | That repository | Members of its workspace | The project's **Settings → Webhooks** | |
| 16 | | A workspace's | Every repository in the workspace | Owners | The workspace's **Settings → Webhooks** | |
| 17 | |
| 18 | ## Add one |
| 19 | |
| 20 | 1. Open **Settings → Webhooks** for the repository or the workspace. |
| 21 | 2. Give the **payload URL**: an HTTPS address on the public internet. |
| 22 | 3. Choose the events, or leave **Everything**, which also includes event |
| 23 | types added later. |
| 24 | 4. Give a **secret**, or leave it empty and g1t makes one. A secret g1t |
| 25 | makes is shown once. |
| 26 | 5. **Add webhook**. g1t sends it a `ping` at once, so you can see straight |
| 27 | away whether your receiver answers. |
| 28 | |
| 29 | ## What is sent |
| 30 | |
| 31 | Each delivery is a `POST` with a JSON body: |
| 32 | |
| 33 | ```json |
| 34 | { |
| 35 | "id": "evt_01m401tecce9h8wt7k3ayvs72n", |
| 36 | "type": "comment.created", |
| 37 | "time": "2026-10-03T04:54:37.708Z", |
| 38 | "workspace": "acme", |
| 39 | "repository": { "id": "rep_cf985171afeee00a62a1c0acb0", "fullName": "acme/web" }, |
| 40 | "actor": { "id": "usr_b51a1a09fc53e9471cbe1426b7", "username": "ada" }, |
| 41 | "data": { "commentId": "cmt_01m401te9eekb92kccgwhympr4", "number": 3, "repoId": "rep_cf985171afeee00a62a1c0acb0" } |
| 42 | } |
| 43 | ``` |
| 44 | |
| 45 | `data` holds what the event is about: ids and numbers to fetch the rest with |
| 46 | the [API](/reference/api/). `actor` is null for something g1t did by |
| 47 | itself. |
| 48 | |
| 49 | With these headers: |
| 50 | |
| 51 | | Header | | |
| 52 | | --- | --- | |
| 53 | | `X-G1t-Event` | The event type, such as `pull.merged`, or `ping`. | |
| 54 | | `X-G1t-Delivery` | The delivery's id. A redelivery has a new one. | |
| 55 | | `X-G1t-Hook` | The webhook's id. | |
| 56 | | `X-G1t-Signature-256` | `sha256=` and the HMAC-SHA256 of the body, keyed with the secret. | |
| 57 | | `User-Agent` | `g1t-webhooks/1` | |
| 58 | |
| 59 | ## Events |
| 60 | |
| 61 | | Event | When | |
| 62 | | --- | --- | |
| 63 | | `git.push` | A branch moved. `data.ref`, `data.after`, `data.defaultBranch`. | |
| 64 | | `repo.created`, `repo.forked` | A repository was made, or forked for a pull request. | |
| 65 | | `issue.opened`, `issue.updated`, `issue.assigned`, `issue.closed`, `issue.reopened` | An issue changed. `data.number`; on close, `data.reason` and `data.resolvedBy`. | |
| 66 | | `comment.created` | A comment or review on an issue or pull request. | |
| 67 | | `pull.opened`, `pull.ready`, `pull.updated`, `pull.merge_requested`, `pull.merged`, `pull.closed` | A pull request changed. `data.number`, `data.issue`; on merge, `data.commit`. | |
| 68 | | `checks.completed` | An issue's acceptance checks finished on a pull request. `data.status` is `passed`, `failed` or `errored`. | |
| 69 | | `review.completed` | A g1t agent reviewed a pull request. `data.verdict`. | |
| 70 | | `workflow.completed` | A GitHub Actions run finished. `data.workflow`, `data.conclusion`, `data.runId`, `data.sha`, `data.pull`. | |
| 71 | | `queue.changed` | The merge queue gained, lost or settled an entry. | |
| 72 | | `session.appended` | An agent's session grew. Busy: choose it only if you need it. | |
| 73 | | `agent.asked` | An agent asked the agent on another pull request a question, or handed it work, while that one was not at work; g1t wakes it to answer. | |
| 74 | |
| 75 | ## Check the signature |
| 76 | |
| 77 | Compute the HMAC-SHA256 of the raw body with your secret and compare it to |
| 78 | `X-G1t-Signature-256` in constant time, before you parse the body. |
| 79 | |
| 80 | ```js |
| 81 | // Node.js |
| 82 | import { createHmac, timingSafeEqual } from "node:crypto"; |
| 83 | |
| 84 | function fromG1t(rawBody, signature, secret) { |
| 85 | const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex"); |
| 86 | return signature?.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected)); |
| 87 | } |
| 88 | ``` |
| 89 | |
| 90 | ```python |
| 91 | # Python |
| 92 | import hashlib, hmac |
| 93 | |
| 94 | def from_g1t(raw_body: bytes, signature: str, secret: str) -> bool: |
| 95 | expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest() |
| 96 | return hmac.compare_digest(signature or "", expected) |
| 97 | ``` |
| 98 | |
| 99 | ## Answering, and retries |
| 100 | |
| 101 | Answer with any 2xx within 10 seconds. Do slow work after answering. |
| 102 | |
| 103 | A delivery that gets anything else, or no answer, is tried again after 1 |
| 104 | minute, 5 minutes, 30 minutes, 2 hours and 5 hours: six attempts over |
| 105 | about seven and a half hours. Then it is marked failed. Pausing or removing |
| 106 | a webhook stops its retries. |
| 107 | |
| 108 | An event is delivered to a webhook once. Use `X-G1t-Delivery`, or the |
| 109 | event's `id`, to ignore one you have already handled. |
| 110 | |
| 111 | ## The delivery log |
| 112 | |
| 113 | Each webhook keeps its deliveries for 14 days. Open **Deliveries** to see, |
| 114 | for each one, the request g1t sent, the status and body your receiver |
| 115 | answered with, how long it took, and when it will be tried again. |
| 116 | **Redeliver** sends the same payload again, as a new delivery. |
| 117 | |
| 118 | The status dot beside each webhook shows how its latest delivery went: |
| 119 | green delivered, amber waiting to try again, red failed. |
| 120 | |
| 121 | ## Addresses |
| 122 | |
| 123 | Webhooks are sent only over HTTPS, to public addresses. Private and local |
| 124 | addresses (`localhost`, `10.0.0.0/8`, `192.168.0.0/16` and the like) are |
| 125 | refused. To receive webhooks on your own machine while you build, use a |
| 126 | tunnel such as Cloudflare Tunnel. |
| 127 | |
| 128 | ## From the API |
| 129 | |
| 130 | The same tools work for a repository's webhooks (give `repo`) and a |
| 131 | workspace's (give `workspace` instead). |
| 132 | |
| 133 | | Tool | Route | |
| 134 | | --- | --- | |
| 135 | | `list_webhooks` | `GET /repos/{owner}/{name}/hooks`, `GET /workspaces/{workspace}/hooks` | |
| 136 | | `create_webhook` | `POST …/hooks` with `url`, `events`, `secret` | |
| 137 | | `update_webhook` | `PATCH …/hooks/{id}` with `url`, `events`, `active` | |
| 138 | | `delete_webhook` | `DELETE …/hooks/{id}` | |
| 139 | | `ping_webhook` | `POST …/hooks/{id}/pings` | |
| 140 | | `list_webhook_deliveries` | `GET …/hooks/{id}/deliveries` | |
| 141 | | `redeliver_webhook` | `POST …/hooks/{id}/deliveries/{delivery}/redeliver` | |
| 142 | |
| 143 | ```sh |
| 144 | curl -X POST https://api.g1t.sh/repos/acme/web/hooks \ |
| 145 | -H "Authorization: Bearer $G1T_TOKEN" -H "Content-Type: application/json" \ |
| 146 | -d '{"url": "https://example.com/g1t", "events": ["pull.merged", "checks.completed"]}' |
| 147 | ``` |