https://github.com/cuedo/github-webhooks
Haskell types and instances for decoding GitHub webhook payloads.
https://github.com/cuedo/github-webhooks
api ci cicd continuous-integration github github-api github-webhooks haskell haskell-lang haskell-language scotty servant warp webhooks
Last synced: 2 months ago
JSON representation
Haskell types and instances for decoding GitHub webhook payloads.
- Host: GitHub
- URL: https://github.com/cuedo/github-webhooks
- Owner: cuedo
- License: mit
- Created: 2017-12-16T06:01:27.000Z (about 8 years ago)
- Default Branch: develop
- Last Pushed: 2025-09-12T00:59:30.000Z (3 months ago)
- Last Synced: 2025-10-04T18:41:55.586Z (3 months ago)
- Topics: api, ci, cicd, continuous-integration, github, github-api, github-webhooks, haskell, haskell-lang, haskell-language, scotty, servant, warp, webhooks
- Language: Haskell
- Homepage: https://hackage.haskell.org/package/github-webhooks
- Size: 924 KB
- Stars: 37
- Watchers: 2
- Forks: 17
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
- Roadmap: ROADMAP.md
- Authors: AUTHORS
Awesome Lists containing this project
README
 \
github-webhooks
---------------
[](https://hackage.haskell.org/package/github-webhooks)
[](#license)
Complete Haskell types and instances for decoding GitHub API [webhook payloads].
### Build Status
| | `release` | `develop` |
|-------------|---------|----------|
| Lints | [](https://github.com/cuedo/github-webhooks/actions/workflows/scan-code.yml) | [](https://github.com/cuedo/github-webhooks/actions/workflows/scan-code.yml) |
| Ubuntu | [](https://github.com/cuedo/github-webhooks/actions/workflows/test-ubuntu-latest.yml) | [](https://github.com/cuedo/github-webhooks/actions/workflows/test-ubuntu-latest.yml) |
| Mac OS | [](https://github.com/cuedo/github-webhooks/actions/workflows/test-macos-latest.yml) | [](https://github.com/cuedo/github-webhooks/actions/workflows/test-macos-latest.yml) |
| Windows | [](https://github.com/cuedo/github-webhooks/actions/workflows/test-windows-latest.yml) | [](https://github.com/cuedo/github-webhooks/actions/workflows/test-windows-latest.yml) |
### Table of Contents
* [Features](#features)
* [Installation](#installation)
* [Examples](#examples)
* [Changelog](#changelog)
* [Roadmap](#roadmap)
* [Authors](#authors)
* [Support](#support)
* [License](#license)
## Features
`github-webhooks` comes with all the bells and whistles:
* **Best-in-class JSON Decoding via `Aeson`**
This library uses the [aeson] package, a fast and widely adopted Haskell library for working with JSON data. It ensures best-in-class JSON decoding, enabling you to parse GitHub webhooks payloads with high performance and accuracy.
* **i18n/Unicode String Support via `Text`**
`github-webhooks` has first-class support for Unicode strings in all functions via the [text] package. This ensures that the library can handle any i18n text data in the payloads correctly, regardless of the character set.
* **Suitable for Large Data Payloads using `Vector`**
This library uses the [vector] package to handle large data payloads efficiently. This means it is suitable for big data workloads and capable of processing large amounts of data without excessive CPU or memory usage.
* **Type-safe Encoding of Optional Data**
Optional data in the payloads are encoded in a type-safe manner (i.e. using `Maybe`). This ensures that your application will not encounter runtime errors due to missing or unexpected data and provides valuable signals during development where you should implement fault handling.
* **Type-safe Event Action Encodings with Support for Future API Changes**
This library encodes event actions in a type-safe manner that does not require the payload to be fully decoded. Thus, applications built using this library will generally be forward-compatible with future changes to the GitHub API and continue to work even if GitHub makes changes to the webhooks API.
* **Instances for `Typeable`, `Data`, `Generic` and `NFData`**
The data types in this library have instances for `Typeable`, `Data`, `Generic`, and `NFData`. This ensures compatibility with a wide range of Haskell libraries and metaprogramming tools.
* **Strongly Typed Utility Classes `EventHasSender`, `EventHasRepo` et al.**
This library provides strongly typed utility classes such as `EventHasSender` and `EventHasRepo` to make it easier to work with the different event types and their associated data. You can define webhook event handlers that work on multiple events.
* **Strict Data Types Suitable for High Performance Streaming Operations**
The data types in this library are strict, making them suitable for high-performance streaming operations. This ensures that your application can process large streams of webhook events efficiently and without space leaks.
* **Full Support for Webhook Event Types**
`github-webhooks` provides full support for [all the GitHub webhook event types](https://developer.github.com/v3/activity/events/types/#event-types--payloads). This means you can handle any event sent by GitHub without having to implement custom parsing or processing logic.
## Installation
`github-webhooks` is available via installation on [Hackage](https://hackage.haskell.org/package/github-webhooks) and [Stackage](https://www.stackage.org/package/github-webhooks).
## Examples
### Minimal interactive example:
Shell:
```hs
$ stack ghci bytestring aeson github-webhooks
import qualified Data.ByteString.Lazy as BSL
import Data.Aeson ( eitherDecode' )
json <- BSL.readFile "fixtures/watch-event.json"
eitherDecode' json :: Either String WatchEvent
```
Output:
```
Right (WatchEvent {
evWatchAction = WatchStartedAction,
evWatchRepo = HookRepository {
whRepoId = 35129377,
whRepoNodeId = "MDg6Q2hlY2tSdW4xMjg2MjAyMjg=",
whRepoName = "public-repo",
whRepoFullName = "baxterthehacker/public-repo",
whRepoOwner = Right (HookUser {
whUserLogin = "baxterthehacker",
whUserId = 6752317,
whUserNodeId = "MDg6Q2hlY2tSdW4xMjg2MjAyMjg=",
whUserAvatarUrl = URL "https://avatars.githubusercontent.com/u/6752317?v=3",
...
```
[](https://codespaces.new/cuedo/github-webhooks)
### Getting started quickly
There are some turnkey integration tutorials in this repository:
* **[Servant Integration (Simple)](./examples/servant-simple#readme)**
Minimal working example of integrating this package with [servant] and [servant-github-webhook].
* **[Servant Integration (Typical)](./examples/servant#readme)**
This example demonstrates more advanced use-cases with [servant] by decoding multiple different types of payloads on the same endpoint.
* **[Scotty Integration](./examples/scotty#readme)**
Minimal working example of integrating this package with [scotty].
## Changelog
See [CHANGELOG.md](./CHANGELOG.md) for a summary of changes in each release.
## Roadmap
See [ROADMAP.md](./ROADMAP.md) for the project timeline and feature estimation of future releases.
## Authors
See [AUTHORS](./AUTHORS) for a list of significant authors.
## Support
The best way to get free community support is to raise a well-written issue in this repository and one of the maintainers will endeavour to respond to it quickly.
If you are using a plugin i.e. [servant-github-webhook](https://github.com/tsani/servant-github-webhook), you might be able to get better support if you raise your issue against that project instead.
For enterprise support, you can write us: [foss@cuedo.com.au](mailto:foss@cuedo.com.au).
## License
`github-webhooks` is free open source software, however you must use it according to the MIT-style [LICENSE](./LICENSE).
MIT License
Copyright (c) 2017-2023 CUEDO CONTROLS P/L (https://cuedo.com.au)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Free open source software, sponsored by CUEDO CONTROLS P/L ([cuedo.com.au](https://cuedo.com.au)). \
\
**Software defined mobility, just-so.**
[webhook payloads]: https://developer.github.com/webhooks/
[aeson]: https://www.stackage.org/package/aeson
[text]: https://www.stackage.org/package/text
[vector]: https://www.stackage.org/package/vector
[servant]: https://www.stackage.org/package/github-webhooks
[servant-github-webhook]: https://www.stackage.org/package/servant-github-webhook
[scotty]: https://www.stackage.org/package/scotty