# Python GitHub Webhooks Framework
**NOTE:** Forked from [github_webhooks](https://github.com/karech/github-webhooks) as I needed to access query params from incoming webhooks for identification.
Simple and lightweight micro framework for quick integration with [GitHub
webhooks][1].
It's based on [FastAPI][3] and [pydantic][4], nothing more!
Async and mypy friendly.
[](https://github.com/morriz/github-webhooks/actions/workflows/ci.yml)
[][2]
## Installation
Just add `github-webhooks-framework2` package.
Example:
* `pip install github-webhooks-framework2`
* `poetry add github-webhooks-framework2`
## Example
Create file `example.py` and copy next code:
```python
import uvicorn
from pydantic import BaseModel
from github_webhooks import create_app
from github_webhooks.schemas import WebhookCommonPayload
# WebhookCommonPayload is based on pydantic.BaseModel
class PullRequestPayload(WebhookCommonPayload):
class Pull(BaseModel):
title: str
url: str
action: str
pull_request: Pull
# Initialize Webhook App
app = create_app()
# Register webhook handler:
# `pull_request` - name of an event to handle
# `PullRequestPayload` - webhook payload will be parsed into this model
@app.hooks.register('pull_request', PullRequestPayload)
async def handler(payload: PullRequestPayload) -> None:
print(f'New pull request {payload.pull_request.title}')
print(f' link: {payload.pull_request.url}')
print(f' author: {payload.sender.login}')
if __name__ == '__main__':
# start uvicorn server
uvicorn.run(app)
```
### Let's have detailed overview.
We start by defining payload [Model][5] to parse incoming [Pull Request Body][6].
```python
class PullRequestPayload(WebhookCommonPayload):
class Pull(BaseModel):
title: str
url: str
action: str
pull_request: Pull
```
In this example we only want to get `action`, `pull_request.title` and `pull_request.url` from payload.
By subclassing `WebhookCommonPayload` model will automatically get `sender`, `repository` and `organization` fields.
Next - we are creating ASGI app (based on FastAPI app)
```python
app = create_app()
```
Optionally we can provide here `secret_token` [Github Webhook secret][7]
```python
app = create_app(secret_token='super-secret-token')
```
And time to define our handler
```python
@app.hooks.register('pull_request', PullRequestPayload)
async def handler(payload: PullRequestPayload) -> None:
print(f'New pull request {payload.pull_request.title}')
print(f' link: {payload.pull_request.url}')
print(f' author: {payload.sender.login}')
```
We are using here `@app.hooks.register` deco, which accepts 2 arguments:
* `event: str` - name of webhook event
* `payload_cls: pydantic.BaseModel` - pydantic model class to parse request, subclassed from `pydantic.BaseModel`
or `WebhookCommonPayload`.
And our handler function must be any of this signatures:
```python
async def handler(payload: PullRequestPayload) -> None:
...
```
```python
async def handler(payload: PullRequestPayload, headers: WebhookHeaders) -> Optional[str]:
# `headers` will be WebhookHeaders model with Github Webhook headers parsed.
...
```
An example setup can be found in `example/server.py`.
## References:
[1]: https://developer.github.com/webhooks/
[2]: https://pypi.python.org/pypi/github-webhooks-framework
[3]: https://fastapi.tiangolo.com/
[4]: https://pydantic-docs.helpmanual.io/
[5]: https://pydantic-docs.helpmanual.io/usage/models/
[6]: https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request
[7]: https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks
## Development
1. Install local venv: `python -m venv .venv`
2. Activate: `. .venv/bin/activate`
3. Install deps with `pip install -r requirements.txt -r requirements-test.txt`
4. When done with packages: `./freeze-requirements.sh`
Raw data
{
"_id": null,
"home_page": "",
"name": "github-webhooks-framework2",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "",
"keywords": "github,webhooks,fastapi",
"author": "",
"author_email": "Maurice Faber <morriz@idiotz.nl>",
"download_url": "https://files.pythonhosted.org/packages/43/e0/8bd9806e6853d111cfd6c6b037d5c224b2839ff7777b01cb4ce55a1f66f4/github-webhooks-framework2-0.1.14.tar.gz",
"platform": null,
"description": "# Python GitHub Webhooks Framework\n\n**NOTE:** Forked from [github_webhooks](https://github.com/karech/github-webhooks) as I needed to access query params from incoming webhooks for identification.\n\nSimple and lightweight micro framework for quick integration with [GitHub\nwebhooks][1]. \nIt's based on [FastAPI][3] and [pydantic][4], nothing more! \nAsync and mypy friendly. \n\n[](https://github.com/morriz/github-webhooks/actions/workflows/ci.yml) \n[][2]\n\n\n## Installation\nJust add `github-webhooks-framework2` package. \nExample: \n* `pip install github-webhooks-framework2`\n* `poetry add github-webhooks-framework2`\n\n\n## Example\nCreate file `example.py` and copy next code:\n```python\nimport uvicorn\nfrom pydantic import BaseModel\n\nfrom github_webhooks import create_app\nfrom github_webhooks.schemas import WebhookCommonPayload\n\n\n# WebhookCommonPayload is based on pydantic.BaseModel\nclass PullRequestPayload(WebhookCommonPayload):\n class Pull(BaseModel):\n title: str\n url: str\n \n action: str\n pull_request: Pull\n \n\n# Initialize Webhook App\napp = create_app()\n\n\n# Register webhook handler:\n# `pull_request` - name of an event to handle\n# `PullRequestPayload` - webhook payload will be parsed into this model\n@app.hooks.register('pull_request', PullRequestPayload)\nasync def handler(payload: PullRequestPayload) -> None:\n print(f'New pull request {payload.pull_request.title}')\n print(f' link: {payload.pull_request.url}')\n print(f' author: {payload.sender.login}')\n\n\nif __name__ == '__main__':\n # start uvicorn server\n uvicorn.run(app)\n```\n \n \n### Let's have detailed overview. \n\nWe start by defining payload [Model][5] to parse incoming [Pull Request Body][6]. \n```python\nclass PullRequestPayload(WebhookCommonPayload):\n class Pull(BaseModel):\n title: str\n url: str\n \n action: str\n pull_request: Pull\n```\nIn this example we only want to get `action`, `pull_request.title` and `pull_request.url` from payload. \nBy subclassing `WebhookCommonPayload` model will automatically get `sender`, `repository` and `organization` fields.\n\n\nNext - we are creating ASGI app (based on FastAPI app)\n```python\napp = create_app()\n```\nOptionally we can provide here `secret_token` [Github Webhook secret][7]\n```python\napp = create_app(secret_token='super-secret-token')\n```\n\nAnd time to define our handler\n```python\n@app.hooks.register('pull_request', PullRequestPayload)\nasync def handler(payload: PullRequestPayload) -> None:\n print(f'New pull request {payload.pull_request.title}')\n print(f' link: {payload.pull_request.url}')\n print(f' author: {payload.sender.login}')\n```\n\nWe are using here `@app.hooks.register` deco, which accepts 2 arguments:\n* `event: str` - name of webhook event\n* `payload_cls: pydantic.BaseModel` - pydantic model class to parse request, subclassed from `pydantic.BaseModel` \nor `WebhookCommonPayload`.\n\nAnd our handler function must be any of this signatures: \n```python\nasync def handler(payload: PullRequestPayload) -> None:\n ...\n```\n```python\nasync def handler(payload: PullRequestPayload, headers: WebhookHeaders) -> Optional[str]:\n # `headers` will be WebhookHeaders model with Github Webhook headers parsed.\n ...\n``` \n\nAn example setup can be found in `example/server.py`.\n\n## References:\n[1]: https://developer.github.com/webhooks/\n[2]: https://pypi.python.org/pypi/github-webhooks-framework\n[3]: https://fastapi.tiangolo.com/\n[4]: https://pydantic-docs.helpmanual.io/\n[5]: https://pydantic-docs.helpmanual.io/usage/models/\n[6]: https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request\n[7]: https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks\n\n## Development\n\n1. Install local venv: `python -m venv .venv`\n2. Activate: `. .venv/bin/activate`\n3. Install deps with `pip install -r requirements.txt -r requirements-test.txt`\n4. When done with packages: `./freeze-requirements.sh`\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "GitHub Webhooks Framework",
"version": "0.1.14",
"project_urls": {
"Bug Tracker": "https://github.com/morriz/github-webhooks/issues",
"Source Code": "https://github.com/morriz/github-webhooks",
"homepage": "https://github.com/morriz/github-webhooks"
},
"split_keywords": [
"github",
"webhooks",
"fastapi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9fc9e186fb22e45176d41d8915927264d522e299ed06e5ff9828397b8c517d4a",
"md5": "b97aa87701e9f40d89ccce6167c49cf5",
"sha256": "32582cf8b66327240af9ef506670edd1ec8baf6502fed189d05be4a83830d256"
},
"downloads": -1,
"filename": "github_webhooks_framework2-0.1.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b97aa87701e9f40d89ccce6167c49cf5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 20776,
"upload_time": "2024-02-12T14:53:36",
"upload_time_iso_8601": "2024-02-12T14:53:36.928695Z",
"url": "https://files.pythonhosted.org/packages/9f/c9/e186fb22e45176d41d8915927264d522e299ed06e5ff9828397b8c517d4a/github_webhooks_framework2-0.1.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "43e08bd9806e6853d111cfd6c6b037d5c224b2839ff7777b01cb4ce55a1f66f4",
"md5": "e3fb5278aef5a21b60885659e107c7da",
"sha256": "67e3e23b29c59ab3f675005de66381fb1f32d424978efdb86291199bde44408a"
},
"downloads": -1,
"filename": "github-webhooks-framework2-0.1.14.tar.gz",
"has_sig": false,
"md5_digest": "e3fb5278aef5a21b60885659e107c7da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 19912,
"upload_time": "2024-02-12T14:53:38",
"upload_time_iso_8601": "2024-02-12T14:53:38.562590Z",
"url": "https://files.pythonhosted.org/packages/43/e0/8bd9806e6853d111cfd6c6b037d5c224b2839ff7777b01cb4ce55a1f66f4/github-webhooks-framework2-0.1.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-12 14:53:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "morriz",
"github_project": "github-webhooks",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "fastapi",
"specs": []
},
{
"name": "pydantic",
"specs": []
}
],
"lcname": "github-webhooks-framework2"
}
JSON
