Typed GitHub webhook events for Java 21: a record for every event GitHub documents (314 events in 88 families, for github.com, GitHub Enterprise Cloud and GitHub Enterprise Server), a decoder, and a receiver that verifies the signature before it parses anything.
- Typed. Every event is a record and every family a sealed interface, so the compiler checks a
switchover the decoded event. - Safe by default. The receiver checks
X-Hub-Signature-256against the raw body in constant time, and a delivery with a bad signature is never parsed. - Stable when GitHub changes. A new event, action, enum value, field or union variant never fails decoding. A known
event that does not fit its record (a required property is missing or
null, or a value has another JSON type) is kept as an unknown event with its body and logged atWARN;fallbackReason()says why (decodeDeliveryandreceiveDeliverycarry it,decodeandreceivereturn the unknown event without the reason). - Light. Synchronous, no HTTP client, no dependency on the REST client. Jackson 3 and a few small modules.
Requirements: Java 21. The library is a Java module, io.github.piotr_janczukowicz.githubwebhook, and also works on
the class path. It is published on
Maven Central:
<dependency>
<groupId>io.github.piotr-janczukowicz</groupId>
<artifactId>github-webhook</artifactId>
<version>LATEST_VERSION</version>
</dependency>Replace LATEST_VERSION with the version in the Maven Central badge at the top of this page, or with the newest entry on
the releases page. The library is new and not yet proven in
production; see the Disclaimer before relying on it.
Build the receiver once with the webhook secret (it is thread-safe) and hand it the two headers and the raw body of every delivery:
GitHubWebhookReceiver receiver = GitHubWebhookReceiver.of(secret); // the webhook secret, as text or bytes
GitHubWebhookEvent event = receiver.receive(
request.header("X-GitHub-Event"), request.header("X-Hub-Signature-256"), request.readBody());
switch (event) {
case GitHubWebhookIssuesOpenedEvent opened -> handle(opened.issue());
case GitHubWebhookIssuesEvent other -> { /* another action of issues, or an action this version does not know */ }
case GitHubWebhookPushEvent push -> handle(push.commits());
case GitHubWebhookUnknownEvent unknown -> log(unknown.eventName());
default -> { }
}receive throws GitHubWebhookSignatureException for a missing or wrong signature (answer with 401) and
GitHubWebhookDecodeException for a body that is empty, above 25 MiB, not a JSON object or over a JSON limit (answer with
400). A body above 25 MiB is refused before the signature is computed. The body must be the bytes exactly as received: a
single changed byte changes the signature.
To rotate a secret, GitHubWebhookReceiver.ofSecrets(List.of(newSecret, oldSecret)) accepts either one. To keep the body
next to the typed event (to queue or forward it), use receiveDelivery, which returns a GitHubWebhookDelivery.
The library is generated from GitHub's OpenAPI descriptions and is not source-stable: a sync can change a component type,
rename a record or add a record to a sealed interface, so end a switch over events with a default.
The decoder has no product check: it decodes whatever it receives. A record or enum that not every product sends is marked
@Flavors; webhook-events.md shows which product sends which event.
| Product | Support |
|---|---|
| GitHub.com | Every event of the description |
| GitHub Enterprise Cloud | Every event; one that only it sends is marked @Flavors(GitHubWebhookFlavor.GHEC) |
| GitHub Enterprise Server | Version 3.22; an event that only it sends is marked @Flavors(GitHubWebhookFlavor.GHES) |
WebhookServerExample is a complete
endpoint on the JDK's own HttpServer (about fifty lines): it takes POST /github/webhook, lets the receiver verify and
decode the delivery, and prints one line per event. Run its main with the environment variable WEBHOOK_SECRET set to the
webhook's secret (the port is the first argument, default 8080), expose it with a tunnel such as ngrok http 8080, and add a
webhook in a repository's Settings with the tunnel URL plus /github/webhook, content type application/json and the same
secret. GitHub's first delivery is a ping.
| Chapter | In short |
|---|---|
| Receiving GitHub webhooks | The receiver, the decoded types, what never fails and what does, the payload map, stability and products |
| Supported events | Every event the library decodes, with the action, the record and the products that send it |
This library is built on the OpenAPI descriptions that GitHub publishes in github/rest-api-description, which are licensed under the MIT license. The caveats of that project apply here too: the descriptions of the webhooks are not always exact, and a payload GitHub sends can differ from its description.
The library is new and not yet proven in production. It is checked against the descriptions and a few real deliveries, not against every event on a live GitHub instance. Verify the behavior of any event you depend on before using it in production.
See LICENSE.