The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 131 lines 4.29 KB
Raw
1 ---
2 title: Webhooks & events
3 description: Provision GitHub repository webhooks as resources, or subscribe a Cloudflare Worker to repository events with typed payloads and verified deliveries.
4 ---
5
6 GitHub tells the world what happened to a repository through
7 webhooks — `POST`s to a URL on every push, pull request, release,
8 and so on. Alchemy gives you two levels of abstraction: the
9 `Webhook` resource manages the webhook itself and points it at any
10 URL, and `consumeRepositoryEvents` subscribes a Cloudflare Worker to
11 a repository with the webhook, routing, and signature verification
12 handled for you.
13
14 ## The Webhook resource
15
16 `GitHub.Webhook` manages a repository webhook's lifecycle — created
17 on the first deploy, updated in place on subsequent deploys, deleted
18 when the stack is destroyed:
19
20 ```typescript
21 import * as GitHub from "@alchemy.run/github";
22
23 yield* GitHub.Webhook("ci-webhook", {
24 owner: "my-org",
25 repository: "my-repo",
26 url: "https://example.com/github",
27 events: ["push", "pull_request"],
28 secret,
29 });
30 ```
31
32 `events` defaults to `["push"]`; pass `["*"]` to receive every event
33 GitHub emits. The `secret` (a `Redacted` string, e.g. from
34 `Config.Redacted` — see [Secrets & env](/cloudflare/security/secrets-env))
35 makes GitHub sign each delivery with `HMAC-SHA256` in the
36 `X-Hub-Signature-256` header so your receiver can verify the payload
37 came from GitHub.
38
39 Credentials come from `GitHub.providers()` — env, stored PAT, or the
40 `gh` CLI (see [setup](/github/setup)). The token needs `repo` scope
41 (admin access to the repository) to manage webhooks.
42
43 ## Point it at another resource
44
45 `url` accepts an `Output<string>`, so the webhook can target a
46 resource provisioned in the same stack:
47
48 ```typescript
49 const worker = yield* Cloudflare.Worker("Api", { ... });
50
51 yield* GitHub.Webhook("repo-webhook", {
52 owner: "my-org",
53 repository: "my-repo",
54 url: worker.url!,
55 events: ["*"],
56 });
57 ```
58
59 At this level the receiving end is yours to build: parsing the
60 payload, routing the delivery path, and verifying signatures. Most
61 of the time you don't want that — read on.
62
63 ## Consume events from a Worker
64
65 `GitHub.consumeRepositoryEvents` subscribes a Cloudflare Worker to a
66 repository and replaces all the plumbing: it provisions the webhook
67 pointing at the Worker, binds the signing secret onto it, claims the
68 delivery path in `fetch`, verifies each delivery's signature, and
69 hands your handler a typed payload:
70
71 ```typescript
72 // src/worker.ts
73 import * as Cloudflare from "@alchemy.run/cloudflare";
74 import * as GitHub from "@alchemy.run/github";
75 import * as Effect from "effect/Effect";
76
77 export default Cloudflare.Worker(
78 "Worker",
79 { main: import.meta.url },
80 Effect.gen(function* () {
81 yield* GitHub.consumeRepositoryEvents(
82 {
83 owner: "my-org",
84 repository: "my-repo",
85 events: ["push", "pull_request"],
86 secret,
87 },
88 (event) => {
89 switch (event.name) {
90 case "push":
91 return Effect.log(`push to ${event.payload.ref}`);
92 case "pull_request":
93 return Effect.log(`PR: ${event.payload.pull_request.title}`);
94 }
95 },
96 );
97
98 // ...your own fetch handler is untouched
99 }).pipe(
100 Effect.provide(GitHub.RepositoryEventSourceLive),
101 ),
102 );
103 ```
104
105 `event` is a typed webhook delivery, narrowed to the events
106 you selected — a `switch` on `event.name` narrows `event.payload`
107 exhaustively. The stack provides both clouds' providers:
108 `Layer.mergeAll(Cloudflare.providers(), GitHub.providers())`.
109
110 For the full walkthrough — runtime layer, secret verification,
111 deploy, and a release-blogging agent built on this event source —
112 see [React to GitHub events from a Worker](/cloudflare/messaging/github-events).
113
114 ## Cloudflare-only today
115
116 `GitHub.RepositoryEventSourceLive` runs on any host that is a
117 `WebhookHost`, and today only Cloudflare Workers are. On other hosts you can
118 still provision a `GitHub.Webhook` directly with any delivery URL,
119 but routing and signature verification are yours to implement.
120
121 ## Where next
122
123 - [React to GitHub events from a Worker](/cloudflare/messaging/github-events)
124 — the goal-oriented guide.
125 - [Repositories](/github/repository) — create and converge the repos
126 these webhooks attach to.
127 - [GitHub setup](/github/setup) — credentials and token scopes.
128
129 Reference:
130
131 - [Webhook API reference](/providers/github/webhook)